@gmickel/gno 1.17.0 → 1.19.0

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

@@ -0,0 +1,303 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "gno://schemas/retrieval-trace-qrels@1.0",
+  "title": "GNO Retrieval Trace Qrels Artifact",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "format", "cases"],
+  "properties": {
+    "schemaVersion": { "const": "1.0" },
+    "format": { "const": "qrels" },
+    "cases": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "#/definitions/case" }
+    }
+  },
+  "definitions": {
+    "hash": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+    "nullableHash": {
+      "oneOf": [{ "$ref": "#/definitions/hash" }, { "type": "null" }]
+    },
+    "evidence": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "docid",
+        "sourceHash",
+        "mirrorHash",
+        "uri",
+        "seq",
+        "startLine",
+        "endLine",
+        "passageHash",
+        "rank",
+        "plannerRank",
+        "score",
+        "sources",
+        "graphExpanded"
+      ],
+      "properties": {
+        "docid": { "type": "string", "minLength": 1 },
+        "sourceHash": { "$ref": "#/definitions/hash" },
+        "mirrorHash": { "$ref": "#/definitions/hash" },
+        "uri": { "type": "string", "pattern": "^gno://" },
+        "seq": {
+          "oneOf": [{ "type": "integer", "minimum": 0 }, { "type": "null" }]
+        },
+        "startLine": { "type": "integer", "minimum": 1 },
+        "endLine": { "type": "integer", "minimum": 1 },
+        "passageHash": { "$ref": "#/definitions/hash" },
+        "rank": {
+          "oneOf": [{ "type": "integer", "minimum": 1 }, { "type": "null" }]
+        },
+        "plannerRank": {
+          "oneOf": [{ "type": "integer", "minimum": 1 }, { "type": "null" }]
+        },
+        "score": {
+          "oneOf": [{ "type": "number" }, { "type": "null" }]
+        },
+        "sources": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "graphExpanded": { "type": "boolean" }
+      }
+    },
+    "target": {
+      "$ref": "gno://schemas/retrieval-trace-payloads@1.0#/definitions/judgmentTarget"
+    },
+    "qrel": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "qrelId",
+        "judgmentId",
+        "label",
+        "relevance",
+        "baselineMissing",
+        "target",
+        "evidence"
+      ],
+      "properties": {
+        "qrelId": { "type": "string", "minLength": 1 },
+        "judgmentId": { "type": "string", "minLength": 1 },
+        "label": {
+          "enum": ["relevant", "irrelevant", "missing_expected"]
+        },
+        "relevance": { "enum": [0, 1] },
+        "baselineMissing": { "type": "boolean" },
+        "target": { "$ref": "#/definitions/target" },
+        "evidence": {
+          "oneOf": [{ "$ref": "#/definitions/evidence" }, { "type": "null" }]
+        }
+      }
+    },
+    "case": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "caseId",
+        "traceId",
+        "retrievalRunId",
+        "terminalStatus",
+        "query",
+        "fingerprints",
+        "baseline",
+        "judgments",
+        "qrels"
+      ],
+      "properties": {
+        "caseId": { "type": "string", "minLength": 1 },
+        "traceId": { "type": "string", "minLength": 1 },
+        "retrievalRunId": { "type": "string", "minLength": 1 },
+        "terminalStatus": {
+          "enum": ["completed", "partial", "failed", "cancelled"]
+        },
+        "query": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["text", "digest", "goalText", "goalDigest", "filters"],
+          "properties": {
+            "text": { "type": "string", "minLength": 1 },
+            "digest": { "$ref": "#/definitions/hash" },
+            "goalText": {
+              "oneOf": [{ "type": "string" }, { "type": "null" }]
+            },
+            "goalDigest": { "$ref": "#/definitions/nullableHash" },
+            "filters": {
+              "$ref": "gno://schemas/retrieval-trace-filters@1.0#/definitions/filters"
+            }
+          }
+        },
+        "fingerprints": {
+          "$ref": "gno://schemas/retrieval-trace-common@1.0#/definitions/fingerprints"
+        },
+        "baseline": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "ranked",
+            "capabilities",
+            "capabilityOutcomes",
+            "fallbackCodes",
+            "outcomes"
+          ],
+          "properties": {
+            "ranked": {
+              "type": "array",
+              "items": { "$ref": "#/definitions/evidence" }
+            },
+            "capabilities": {
+              "type": "array",
+              "items": { "type": "string", "minLength": 1 }
+            },
+            "capabilityOutcomes": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["capability", "status", "reasonCode"],
+                "properties": {
+                  "capability": { "type": "string" },
+                  "status": {
+                    "enum": ["attempted", "used", "unavailable", "failed"]
+                  },
+                  "reasonCode": {
+                    "oneOf": [{ "type": "string" }, { "type": "null" }]
+                  }
+                }
+              }
+            },
+            "fallbackCodes": {
+              "type": "array",
+              "items": { "type": "string" }
+            },
+            "outcomes": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["opened", "cited", "pinned"],
+              "properties": {
+                "opened": {
+                  "type": "array",
+                  "items": { "$ref": "#/definitions/evidence" }
+                },
+                "cited": {
+                  "type": "array",
+                  "items": { "$ref": "#/definitions/evidence" }
+                },
+                "pinned": {
+                  "type": "array",
+                  "items": { "$ref": "#/definitions/evidence" }
+                }
+              }
+            }
+          }
+        },
+        "judgments": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["history", "effective"],
+          "properties": {
+            "history": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": [
+                  "judgmentId",
+                  "label",
+                  "targetKind",
+                  "target",
+                  "createdAtMs",
+                  "canonicalDigest"
+                ],
+                "properties": {
+                  "judgmentId": { "type": "string" },
+                  "label": {
+                    "enum": ["relevant", "irrelevant", "missing_expected"]
+                  },
+                  "targetKind": {
+                    "enum": ["document", "chunk", "span", "query"]
+                  },
+                  "target": { "$ref": "#/definitions/target" },
+                  "createdAtMs": { "type": "integer", "minimum": 0 },
+                  "canonicalDigest": { "$ref": "#/definitions/hash" }
+                },
+                "allOf": [
+                  {
+                    "if": {
+                      "properties": {
+                        "targetKind": { "const": "document" }
+                      },
+                      "required": ["targetKind"]
+                    },
+                    "then": {
+                      "properties": {
+                        "target": {
+                          "$ref": "gno://schemas/retrieval-trace-payloads@1.0#/definitions/documentTarget"
+                        }
+                      }
+                    }
+                  },
+                  {
+                    "if": {
+                      "properties": { "targetKind": { "const": "chunk" } },
+                      "required": ["targetKind"]
+                    },
+                    "then": {
+                      "properties": {
+                        "target": {
+                          "allOf": [
+                            { "$ref": "#/definitions/target" },
+                            {
+                              "type": "object",
+                              "properties": { "seq": {} },
+                              "required": ["seq"]
+                            }
+                          ]
+                        }
+                      }
+                    }
+                  },
+                  {
+                    "if": {
+                      "properties": { "targetKind": { "const": "span" } },
+                      "required": ["targetKind"]
+                    },
+                    "then": {
+                      "properties": {
+                        "target": {
+                          "allOf": [
+                            { "$ref": "#/definitions/target" },
+                            {
+                              "type": "object",
+                              "properties": {
+                                "startLine": {},
+                                "endLine": {}
+                              },
+                              "required": ["startLine", "endLine"]
+                            }
+                          ]
+                        }
+                      }
+                    }
+                  }
+                ]
+              }
+            },
+            "effective": {
+              "type": "array",
+              "items": { "type": "string" }
+            }
+          }
+        },
+        "qrels": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "$ref": "#/definitions/qrel" }
+        }
+      }
+    }
+  }
+}

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

@@ -0,0 +1,286 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "gno://schemas/retrieval-trace-replay@1.0",
+  "title": "GNO Retrieval Trace Replay",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "exportId",
+    "candidate",
+    "verdict",
+    "reason",
+    "recommendation",
+    "applied",
+    "cases"
+  ],
+  "properties": {
+    "schemaVersion": { "const": "1.0" },
+    "exportId": { "type": "string", "minLength": 1, "maxLength": 128 },
+    "candidate": {
+      "type": "object",
+      "required": ["id", "type"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1, "maxLength": 128 },
+        "type": { "enum": ["bm25", "vector", "hybrid"] },
+        "limit": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 10000
+        },
+        "candidateLimit": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 10000
+        },
+        "noExpand": { "type": "boolean" },
+        "noRerank": { "type": "boolean" },
+        "queryModes": {
+          "type": "array",
+          "maxItems": 100,
+          "uniqueItems": true,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["mode", "text"],
+            "properties": {
+              "mode": { "enum": ["term", "intent", "hyde"] },
+              "text": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 8192
+              }
+            }
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "verdict": {
+      "enum": ["improved", "unchanged", "regressed", "unreplayable"]
+    },
+    "reason": {
+      "oneOf": [
+        {
+          "enum": [
+            "manifest_missing",
+            "manifest_hash_mismatch",
+            "trace_missing",
+            "redaction_incompatible",
+            "query_missing",
+            "filters_incomplete",
+            "no_retrieval_run",
+            "ambiguous_missing_expected_run",
+            "source_stale",
+            "source_missing",
+            "candidate_failed"
+          ]
+        },
+        { "type": "null" }
+      ]
+    },
+    "recommendation": {
+      "enum": ["promote", "keep_baseline", "manual_review"]
+    },
+    "applied": { "const": false },
+    "cases": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "caseId",
+          "traceId",
+          "terminalStatus",
+          "verdict",
+          "reason",
+          "metrics",
+          "fingerprints",
+          "capabilityOutcomes",
+          "fallbackCodes",
+          "qrels"
+        ],
+        "properties": {
+          "caseId": { "type": "string" },
+          "traceId": { "type": "string" },
+          "terminalStatus": {
+            "enum": ["completed", "partial", "failed", "cancelled"]
+          },
+          "verdict": {
+            "enum": ["improved", "unchanged", "regressed", "unreplayable"]
+          },
+          "reason": {
+            "oneOf": [
+              { "$ref": "#/properties/reason/oneOf/0" },
+              { "type": "null" }
+            ]
+          },
+          "metrics": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "baseline",
+              "candidate",
+              "baselineCoverage",
+              "candidateCoverage"
+            ],
+            "properties": {
+              "baseline": { "$ref": "#/definitions/metrics" },
+              "candidate": { "$ref": "#/definitions/metrics" },
+              "baselineCoverage": { "type": "number" },
+              "candidateCoverage": { "type": "number" }
+            }
+          },
+          "fingerprints": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["original", "current", "candidate"],
+            "properties": {
+              "original": {
+                "$ref": "gno://schemas/retrieval-trace-common@1.0#/definitions/fingerprints"
+              },
+              "current": {
+                "$ref": "gno://schemas/retrieval-trace-common@1.0#/definitions/fingerprints"
+              },
+              "candidate": {
+                "$ref": "gno://schemas/retrieval-trace-common@1.0#/definitions/fingerprints"
+              }
+            }
+          },
+          "capabilityOutcomes": {
+            "type": "object",
+            "required": ["baseline", "candidate"],
+            "properties": {
+              "baseline": {
+                "type": "array",
+                "items": { "$ref": "#/definitions/capabilityOutcome" }
+              },
+              "candidate": {
+                "type": "array",
+                "items": { "$ref": "#/definitions/capabilityOutcome" }
+              }
+            },
+            "additionalProperties": false
+          },
+          "fallbackCodes": {
+            "type": "object",
+            "required": ["baseline", "candidate"],
+            "properties": {
+              "baseline": {
+                "type": "array",
+                "items": { "type": "string" }
+              },
+              "candidate": {
+                "type": "array",
+                "items": { "type": "string" }
+              }
+            },
+            "additionalProperties": false
+          },
+          "qrels": {
+            "type": "array",
+            "items": { "$ref": "#/definitions/qrelResult" }
+          }
+        }
+      }
+    }
+  },
+  "definitions": {
+    "capabilityOutcome": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["capability", "status", "reasonCode"],
+      "properties": {
+        "capability": { "type": "string", "minLength": 1 },
+        "status": {
+          "enum": ["attempted", "used", "unavailable", "failed"]
+        },
+        "reasonCode": {
+          "oneOf": [{ "type": "string" }, { "type": "null" }]
+        }
+      }
+    },
+    "metrics": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["precisionAtK", "recallAtK", "f1AtK", "mrr", "ndcgAtK"],
+      "properties": {
+        "precisionAtK": { "type": "number" },
+        "recallAtK": { "type": "number" },
+        "f1AtK": { "type": "number" },
+        "mrr": { "type": "number" },
+        "ndcgAtK": { "type": "number" }
+      }
+    },
+    "qrelResult": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "qrelId",
+        "label",
+        "relevance",
+        "baselineRank",
+        "plannerRank",
+        "candidateRank",
+        "rankDelta",
+        "opened",
+        "cited",
+        "pinned",
+        "sourceState",
+        "diagnostic"
+      ],
+      "properties": {
+        "qrelId": { "type": "string" },
+        "label": {
+          "enum": ["relevant", "irrelevant", "missing_expected"]
+        },
+        "relevance": { "enum": [0, 1] },
+        "baselineRank": {
+          "oneOf": [{ "type": "integer" }, { "type": "null" }]
+        },
+        "plannerRank": {
+          "oneOf": [{ "type": "integer" }, { "type": "null" }]
+        },
+        "candidateRank": {
+          "oneOf": [{ "type": "integer" }, { "type": "null" }]
+        },
+        "rankDelta": {
+          "oneOf": [{ "type": "integer" }, { "type": "null" }]
+        },
+        "opened": { "type": "boolean" },
+        "cited": { "type": "boolean" },
+        "pinned": { "type": "boolean" },
+        "sourceState": {
+          "enum": [
+            "unchanged",
+            "stale",
+            "missing",
+            "inactive",
+            "no_indexed_content"
+          ]
+        },
+        "diagnostic": {
+          "oneOf": [
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["status", "filterReasons", "stageDropReasons"],
+              "properties": {
+                "status": { "type": "string" },
+                "filterReasons": {
+                  "type": "array",
+                  "items": { "type": "string" }
+                },
+                "stageDropReasons": {
+                  "type": "array",
+                  "items": { "type": "string" }
+                }
+              }
+            },
+            { "type": "null" }
+          ]
+        }
+      }
+    }
+  }
+}

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

@@ -0,0 +1,69 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "gno://schemas/retrieval-trace-show@1.0",
+  "title": "GNO Retrieval Trace Detail",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "trace",
+    "runs",
+    "events",
+    "judgments",
+    "exports",
+    "totals",
+    "truncated"
+  ],
+  "properties": {
+    "schemaVersion": { "const": "1.0" },
+    "trace": {
+      "$ref": "gno://schemas/retrieval-trace-common@1.0#/definitions/trace"
+    },
+    "runs": {
+      "type": "array",
+      "items": {
+        "$ref": "gno://schemas/retrieval-trace-common@1.0#/definitions/run"
+      }
+    },
+    "events": {
+      "type": "array",
+      "items": {
+        "$ref": "gno://schemas/retrieval-trace-common@1.0#/definitions/event"
+      }
+    },
+    "judgments": {
+      "type": "array",
+      "items": {
+        "$ref": "gno://schemas/retrieval-trace-common@1.0#/definitions/judgment"
+      }
+    },
+    "exports": {
+      "type": "array",
+      "items": {
+        "$ref": "gno://schemas/retrieval-trace-common@1.0#/definitions/exportRow"
+      }
+    },
+    "totals": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["runs", "events", "judgments", "exports"],
+      "properties": {
+        "runs": { "type": "integer", "minimum": 0 },
+        "events": { "type": "integer", "minimum": 0 },
+        "judgments": { "type": "integer", "minimum": 0 },
+        "exports": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "truncated": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["runs", "events", "judgments", "exports"],
+      "properties": {
+        "runs": { "type": "boolean" },
+        "events": { "type": "boolean" },
+        "judgments": { "type": "boolean" },
+        "exports": { "type": "boolean" }
+      }
+    }
+  }
+}