obligations.vocabulary
The tokens a task may declare in `requires`: what each one asks of a worker, the command that discharges it, the pathspecs its evidence is hashed over, and whether its fact is remote and therefore bound to a commit rather than to a tree. Shipped data, identical in every clone, so this answers in a checkout that has never run the lifecycle.
The tokens a task may declare in `requires`: what each one asks of a worker, the command that discharges it, the pathspecs its evidence is hashed over, and whether its fact is remote and therefore bound to a commit rather than to a tree. Shipped data, identical in every clone, so this answers in a checkout that has never run the lifecycle.
- query
- behaviorally_verified
- module obligations
- #obligations
- #completion
Exposure
Where this one definition is reachable. Absence is explicit: a surface not listed does not carry it.
| surface | as |
|---|---|
| MCP | tool majordomus_obligations resource majordomus://obligations |
| HTTP | GET /api/v1/obligations operationId obligations.vocabulary |
| command line | — |
Schemas
The canonical input and output, from the Rust types; the MCP tool schema and the OpenAPI parameters and responses are derived from these.
input · Empty
No input.
No properties: the capability takes no input.
JSON Schema
{
"additionalProperties": false,
"description": "No input.",
"title": "Empty",
"type": "object"
}output · Vocabulary
The vocabulary the distribution ships: every token there is. `count` is measured from `obligations` rather than written down, so a token added to the file is counted by the same act that declares it. ``` use majordomus_cli::capability::builtin::obligations::Vocabulary; let v: Vocabulary = serde_json::from_str( r#"{"version":1,"source":"/opt/majordomus/share/obligations.yaml","count":1, "obligations":[{"id":"commit","title":"The work is committed", "summary":"In the branch's history, not the working tree.", "discharged_by":"git","remote":false}]}"#, ) .unwrap(); assert_eq!(v.count, v.obligations.len()); assert_eq!(v.version, 1, "the only shape this reader accepts"); ```
| property | type | required | description |
|---|---|---|---|
| count | integer | yes | How many tokens there are. No number anywhere is written down. |
| obligations | array | yes | Every token, in the order the file declares them. |
| source | string | yes | Where it was read from, absolute: the distribution's share directory, which is not necessarily inside the repository. |
| version | integer | yes | The file's own format version. `1` is the only one this reader accepts. |
JSON Schema
{
"$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"
}Policies
- benchmark
- required — a target on every transport the exposure declares; the cases are the input type's
- cache
- process — up to 2 entries in the process, scoped by the registry fingerprint
Benchmark targets
Derived from the registry for this repository: one requirement per transport, and the cases the input type provides. The whole matrix is on the benchmarks page.