obligations.vocabulary

{
  "additionalProperties": false,
  "description": "No input.",
  "title": "Empty",
  "type": "object"
}

{
  "$defs": {
    "Obligation": {
      "description": "One token a task may declare in `requires`, as the distribution ships it.\n\n`remote` and `inputs` are what decide how its evidence is judged, and they are the\nfile's decision rather than this reader's: a fact the working tree cannot establish is\nbound to the commit it was taken at, and everything else is bound to the bytes of the\nfiles its pathspecs select.\n\n```\nuse majordomus_cli::capability::builtin::obligations::Obligation;\nlet push: Obligation = serde_json::from_str(\n    r#\"{\"id\":\"push\",\"title\":\"The commit reached the remote\",\n        \"summary\":\"The branch's head exists on the remote it tracks.\",\n        \"discharged_by\":\"git\",\"remote\":true}\"#,\n)\n.unwrap();\nassert!(push.remote);\nassert!(push.inputs.is_empty(), \"a remote fact is bound to a commit, not to a tree\");\n```",
      "properties": {
        "discharged_by": {
          "description": "The command that produces the evidence. `none` for a token held by another line of\nthe contract and listed so that a report can say it rather than leave a hole.",
          "type": "string"
        },
        "id": {
          "description": "The token, as a task's `requires` names it.",
          "type": "string"
        },
        "inputs": {
          "description": "The pathspecs the evidence is hashed over. Empty for a token whose fact is remote,\nand empty for one bound to neither: see `ObligationClosure::staleness`.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "note": {
          "description": "What the vocabulary says about the token beyond its summary.",
          "type": "string"
        },
        "remote": {
          "description": "True when the fact cannot be established from the working tree alone — a push, a\npublication, a deployment. Such evidence is bound to a commit, not to a tree.",
          "type": "boolean"
        },
        "summary": {
          "description": "What a worker is being asked to have done.",
          "type": "string"
        },
        "title": {
          "description": "The obligation as a heading.",
          "type": "string"
        }
      },
      "required": [
        "id",
        "title",
        "summary",
        "discharged_by",
        "remote"
      ],
      "type": "object"
    }
  },
  "description": "The vocabulary the distribution ships: every token there is.\n\n`count` is measured from `obligations` rather than written down, so a token added to\nthe file is counted by the same act that declares it.\n\n```\nuse majordomus_cli::capability::builtin::obligations::Vocabulary;\nlet v: Vocabulary = serde_json::from_str(\n    r#\"{\"version\":1,\"source\":\"/opt/majordomus/share/obligations.yaml\",\"count\":1,\n        \"obligations\":[{\"id\":\"commit\",\"title\":\"The work is committed\",\n                        \"summary\":\"In the branch's history, not the working tree.\",\n                        \"discharged_by\":\"git\",\"remote\":false}]}\"#,\n)\n.unwrap();\nassert_eq!(v.count, v.obligations.len());\nassert_eq!(v.version, 1, \"the only shape this reader accepts\");\n```",
  "properties": {
    "count": {
      "description": "How many tokens there are. No number anywhere is written down.",
      "format": "uint",
      "minimum": 0,
      "type": "integer"
    },
    "obligations": {
      "description": "Every token, in the order the file declares them.",
      "items": {
        "$ref": "#/$defs/Obligation"
      },
      "type": "array"
    },
    "source": {
      "description": "Where it was read from, absolute: the distribution's share directory, which is not\nnecessarily inside the repository.",
      "type": "string"
    },
    "version": {
      "description": "The file's own format version. `1` is the only one this reader accepts.",
      "format": "uint64",
      "minimum": 0,
      "type": "integer"
    }
  },
  "required": [
    "version",
    "source",
    "count",
    "obligations"
  ],
  "title": "Vocabulary",
  "type": "object"
}