@intentius/chant 0.90.0 → 0.93.0

package/src/workspace/points-write.schema.json

@@ -0,0 +1,499 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/chant/schemas/workspace/points-write/v1/points-write.schema.json",
+  "title": "chant workspace points ask and answer output",
+  "description": "What `chant workspace points ask` and `points answer` print (ws-058, #2739): the answer record asked for or written, as `points --json` lists a question. ask returns the record that is there when the same point, declaration and inputs were answered or proposed before (reused), and otherwise writes one: answered from a table, proposed from a model at or above its threshold, escalated to people below it. answer records people's answer to an open question once the point's quorum is met. Nothing is committed to the working branch, and nothing is written on a refusal or with --dry-run. In a steward's turn a new record goes on the lifecycle ledger instead of the working tree (#2786), as a commit on chant/lifecycle, and a record already held there is rewritten there. The error codes are a closed list, each in the one closed list of `reason-codes.ts`. Written at contract version 1 of the write documents.",
+  "oneOf": [
+    {
+      "$ref": "#/$defs/result"
+    },
+    {
+      "$ref": "#/$defs/failure"
+    }
+  ],
+  "$defs": {
+    "result": {
+      "description": "The record was found or written. Exit code 0.",
+      "type": "object",
+      "required": [
+        "$schema",
+        "contract",
+        "verb",
+        "kind",
+        "id",
+        "path",
+        "reused",
+        "written",
+        "dryRun",
+        "question"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/points-write/v1/points-write.schema.json"
+        },
+        "contract": {
+          "const": 1
+        },
+        "verb": {
+          "enum": [
+            "ask",
+            "answer"
+          ]
+        },
+        "kind": {
+          "type": "object",
+          "required": [
+            "name",
+            "schema",
+            "file"
+          ],
+          "properties": {
+            "name": {
+              "type": "string"
+            },
+            "schema": {
+              "type": "string"
+            },
+            "file": {
+              "type": "string"
+            }
+          }
+        },
+        "id": {
+          "type": "string"
+        },
+        "path": {
+          "type": "string",
+          "description": "The record file, from the repository root."
+        },
+        "reused": {
+          "type": "boolean",
+          "description": "The record was already there, and nothing new was written."
+        },
+        "written": {
+          "type": "boolean",
+          "description": "A file was written: false when reused, and with --dry-run."
+        },
+        "dryRun": {
+          "type": "boolean"
+        },
+        "question": {
+          "$ref": "#/$defs/question"
+        },
+        "text": {
+          "type": "string",
+          "description": "With --dry-run, the text that would be written."
+        },
+        "error": false
+      }
+    },
+    "question": {
+      "type": "object",
+      "required": [
+        "id",
+        "path",
+        "point",
+        "title",
+        "subject",
+        "state",
+        "open",
+        "questionType",
+        "candidates",
+        "inputs",
+        "inputsHash",
+        "pointVersion",
+        "current",
+        "answer",
+        "decider",
+        "probabilities",
+        "confidence",
+        "threshold",
+        "model",
+        "escalations",
+        "answeredBy",
+        "askedOn",
+        "answeredOn",
+        "valid",
+        "warnings"
+      ],
+      "properties": {
+        "id": {
+          "type": "string"
+        },
+        "path": {
+          "type": "string"
+        },
+        "point": {
+          "type": "string"
+        },
+        "title": {
+          "type": "string"
+        },
+        "subject": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "What the question is about, such as a work item's id."
+        },
+        "state": {
+          "enum": [
+            "escalated",
+            "proposed",
+            "answered"
+          ]
+        },
+        "open": {
+          "type": "boolean",
+          "description": "Escalated to people, or proposed by a model and not yet confirmed."
+        },
+        "questionType": {
+          "type": "string"
+        },
+        "candidates": {
+          "type": "array",
+          "items": {
+            "oneOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "boolean"
+              }
+            ]
+          }
+        },
+        "inputs": {
+          "type": "object"
+        },
+        "inputsHash": {
+          "type": "string"
+        },
+        "pointVersion": {
+          "type": "string"
+        },
+        "current": {
+          "type": [
+            "boolean",
+            "null"
+          ],
+          "description": "The point is still declared as it was when asked; null when the points file no longer declares it."
+        },
+        "answer": {
+          "oneOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "boolean"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "decider": {
+          "type": "object",
+          "description": "Who answered: a table row, a model with its backend and model id, or a quorum, with who answered once people did. For an escalated question, the quorum it waits on."
+        },
+        "probabilities": {
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "type": "object",
+              "additionalProperties": {
+                "type": "number",
+                "minimum": 0,
+                "maximum": 1
+              }
+            }
+          ]
+        },
+        "confidence": {
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "type": "number",
+              "minimum": 0,
+              "maximum": 1
+            }
+          ]
+        },
+        "threshold": {
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "type": "number",
+              "minimum": 0,
+              "maximum": 1
+            }
+          ]
+        },
+        "model": {
+          "description": "Any model answer: the proposal (observed), or the last answer below a model decider's threshold (not observed). null when no model answered.",
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "type": "object",
+              "required": [
+                "answer",
+                "confidence",
+                "threshold",
+                "model",
+                "backend",
+                "observed"
+              ],
+              "properties": {
+                "answer": {
+                  "oneOf": [
+                    {
+                      "type": "string"
+                    },
+                    {
+                      "type": "boolean"
+                    },
+                    {
+                      "type": "null"
+                    }
+                  ]
+                },
+                "confidence": {
+                  "oneOf": [
+                    {
+                      "type": "null"
+                    },
+                    {
+                      "type": "number",
+                      "minimum": 0,
+                      "maximum": 1
+                    }
+                  ]
+                },
+                "threshold": {
+                  "oneOf": [
+                    {
+                      "type": "null"
+                    },
+                    {
+                      "type": "number",
+                      "minimum": 0,
+                      "maximum": 1
+                    }
+                  ]
+                },
+                "model": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "backend": {
+                  "type": [
+                    "string",
+                    "null"
+                  ]
+                },
+                "observed": {
+                  "type": "boolean"
+                }
+              }
+            }
+          ]
+        },
+        "escalations": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "kind",
+              "reason"
+            ],
+            "properties": {
+              "kind": {
+                "enum": [
+                  "table",
+                  "model"
+                ]
+              },
+              "reason": {
+                "type": "string"
+              },
+              "backend": {
+                "type": "string"
+              },
+              "model": {
+                "type": "string"
+              },
+              "answer": {
+                "oneOf": [
+                  {
+                    "type": "string"
+                  },
+                  {
+                    "type": "boolean"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ]
+              },
+              "probabilities": {
+                "type": "object",
+                "additionalProperties": {
+                  "type": "number",
+                  "minimum": 0,
+                  "maximum": 1
+                }
+              },
+              "confidence": {
+                "type": "number",
+                "minimum": 0,
+                "maximum": 1
+              },
+              "threshold": {
+                "type": "number",
+                "minimum": 0,
+                "maximum": 1
+              }
+            }
+          }
+        },
+        "answeredBy": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "ledger": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "Where the record is held when it is on the lifecycle ledger rather than in the working tree (#2786): chant/lifecycle:<path>, which git show reads. A question asked in a steward's turn is held there, since a steward never writes the checkout; people's answer to it is written there too. null for a record in the working tree. path is where the record reads as being either way."
+        },
+        "askedOn": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "answeredOn": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "valid": {
+          "type": "boolean"
+        },
+        "warnings": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "code",
+              "message"
+            ],
+            "properties": {
+              "code": {
+                "enum": [
+                  "asset-drift",
+                  "asset-missing",
+                  "asset-stale",
+                  "record-supersedes-pending",
+                  "record-no-evidence",
+                  "review-undigested",
+                  "source-transcript-drift",
+                  "answer-points-unreadable",
+                  "answer-point-unknown",
+                  "answer-point-changed",
+                  "record-unattested"
+                ]
+              },
+              "message": {
+                "type": "string"
+              }
+            }
+          }
+        }
+      }
+    },
+    "failure": {
+      "description": "Nothing was written. Exit code 1.",
+      "type": "object",
+      "required": [
+        "$schema",
+        "contract",
+        "verb",
+        "error"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/points-write/v1/points-write.schema.json"
+        },
+        "contract": {
+          "const": 1
+        },
+        "verb": {
+          "enum": [
+            "ask",
+            "answer"
+          ]
+        },
+        "error": {
+          "type": "object",
+          "required": [
+            "code",
+            "message"
+          ],
+          "properties": {
+            "code": {
+              "enum": [
+                "kind-unreadable",
+                "kind-invalid",
+                "schema-unreadable",
+                "schema-id-mismatch",
+                "schema-invalid",
+                "location-missing",
+                "write-usage-invalid",
+                "write-input-invalid",
+                "points-undeclared",
+                "points-invalid",
+                "point-unknown",
+                "point-inputs-invalid",
+                "point-decider-failed",
+                "answer-not-candidate",
+                "quorum-not-met",
+                "answer-in-steward-turn",
+                "record-not-found",
+                "record-closed",
+                "record-id-taken",
+                "record-unparseable",
+                "record-schema-invalid",
+                "record-id-duplicate",
+                "record-supersedes-unknown",
+                "record-supersedes-conflict",
+                "record-remediates-unknown",
+                "record-remediates-not-closed",
+                "session-seal-mismatch",
+                "session-verdict-unknown-record"
+              ]
+            },
+            "message": {
+              "type": "string"
+            }
+          }
+        },
+        "question": false
+      }
+    }
+  }
+}