capabilities.describe
One capability by canonical id: its kind, schemas, provenance, stability, exposures, benchmark and cache policy.
One capability by canonical id: its kind, schemas, provenance, stability, exposures, benchmark and cache policy.
- query
- behaviorally_verified
- module capabilities
- #introspection
Exposure
Where this one definition is reachable. Absence is explicit: a surface not listed does not carry it.
| surface | as |
|---|---|
| MCP | tool majordomus_capability |
| HTTP | GET /api/v1/capability operationId capabilities.describe |
| command line | majordomus capabilities describe |
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 · DescribeInput
The input of `capabilities.describe`: which capability.
| property | type | required | description |
|---|---|---|---|
| id | string | yes | The canonical id, e.g. `repository.info` or `rule.majordomus.scope-integrity@1`. |
JSON Schema
{
"additionalProperties": false,
"description": "The input of `capabilities.describe`: which capability.",
"properties": {
"id": {
"description": "The canonical id, e.g. `repository.info` or `rule.majordomus.scope-integrity@1`.",
"type": "string"
}
},
"required": [
"id"
],
"title": "DescribeInput",
"type": "object"
}output · Capability
The canonical descriptor. Everything a projection may say about a capability is here.
| property | type | required | description |
|---|---|---|---|
| availability | reference | yes | Where it means anything: classified from the kind and the transports above, so that a projection reads a field instead of deciding for itself. |
| benchmark | reference | yes | Whether it is a benchmark target; the cases come from the input type. |
| cache | reference | yes | Whether the executor keeps its results. |
| description | string | yes | The one-paragraph description every projection shows. |
| execution | reference | yes | What running it as an execution means: classified from the kind, so that a client reads a fact rather than deciding for itself. |
| exposure | reference | yes | Where it is projected; absence is explicit. |
| id | reference | yes | The canonical identity. |
| input | reference | yes | The canonical schema of the input; an empty object for a resource. |
| kind | reference | yes | Query, command or resource. |
| module | reference | yes | The module that composes it: the id's namespace for a builtin, the kind for a declarative object. |
| output | reference | yes | The canonical schema of the output; the object view for a resource. |
| provenance | reference | yes | Where it came from. |
| stability | reference | yes | Where it stands. |
| tags | array | no | Free tags, from the declarative object's `tags` or the descriptor. |
| title | string | yes | The short name every projection shows. |
| visibility | reference | yes | Who it is for: classified from the same transports. |
JSON Schema
{
"$defs": {
"BenchmarkPolicy": {
"description": "Whether the capability is a benchmark target. `Required` is the default and the norm:\nevery executable capability is timed directly and through every transport it is\nexposed on, with the cases its input type provides.",
"oneOf": [
{
"description": "Timed directly and through every exposure; coverage fails without a case.",
"properties": {
"policy": {
"const": "required",
"type": "string"
}
},
"required": [
"policy"
],
"type": "object"
},
{
"description": "Not timed, for the typed reason; coverage reports it as waived, never as covered.",
"properties": {
"policy": {
"const": "waived",
"type": "string"
},
"reason": {
"$ref": "#/$defs/WaiverReason",
"description": "Why."
}
},
"required": [
"policy",
"reason"
],
"type": "object"
}
]
},
"CachePolicy": {
"description": "Whether, and how, the executor keeps results of this capability. Cache lives in the\nexecutor and nowhere else, so MCP, HTTP and the command line share one; the key is the\ncanonical id, the normalised input and the registry fingerprint, so a changed\nrepository never answers from an old entry.",
"oneOf": [
{
"description": "Every call runs the handler.",
"properties": {
"policy": {
"const": "disabled",
"type": "string"
}
},
"required": [
"policy"
],
"type": "object"
},
{
"description": "Results are kept in this process's memory, bounded, for equal inputs.",
"properties": {
"max_entries": {
"description": "The most entries kept for this capability; the oldest is evicted first.",
"format": "uint",
"minimum": 0,
"type": "integer"
},
"policy": {
"const": "process",
"type": "string"
},
"ttl_seconds": {
"description": "Seconds an entry stays valid; `None` for the life of the process.",
"format": "uint64",
"minimum": 0,
"type": [
"integer",
"null"
]
}
},
"required": [
"policy",
"max_entries"
],
"type": "object"
}
]
},
"CanonicalSchema": {
"description": "A JSON Schema with, when the type has one, a stable component name (the type's title).",
"properties": {
"name": {
"description": "The component name projections use (`RepositoryInfo`); `None` for an anonymous\nschema such as the empty input.",
"type": [
"string",
"null"
]
},
"schema": {
"description": "The schema itself, without `$schema`; nested types live under `$defs`."
}
},
"required": [
"schema"
],
"type": "object"
},
"CapabilityAvailability": {
"description": "Where a capability means anything: the environment a caller must be in for it to\nanswer at all.\n\nThe published site and the running server are genuinely different places. Without this\non the model, every template grows its own idea of what works where — and the usual\nshape that takes is a condition on the page's own address, which is a rule hidden\nwhere nobody will find it and nothing can test it. This is the only thing a projection\nmay ask.\n\nIt is classified rather than declared: the facts that decide it — what kind of thing\nthis is and which transports it is projected through — are already on the descriptor,\nand asking each declaration to restate them would be the same knowledge written twice.\n[`Availability::classify`] is the one place the rule lives.",
"oneOf": [
{
"const": "always",
"description": "True in every environment, a published page with no server included: the layer's\nown content, which a build renders and a process serves from the same index.",
"type": "string"
},
{
"const": "runtime",
"description": "A process must be running to answer: everything with a handler, whether it is\nreached over HTTP, over MCP or from the command line.",
"type": "string"
},
{
"const": "build_time",
"description": "A value captured when the site was generated, rendered afterwards as the capture\nit is. Nothing classifies to this yet; the static projection of the graph is what\nwill declare it, and it is on the model so that a captured value can be labelled\nas captured instead of being shown as current.",
"type": "string"
},
{
"const": "authenticated",
"description": "A process must be running and the caller must be one it has authenticated. Nothing\nin this repository authenticates a caller yet; a surface that does will say so\nhere rather than in the template that renders its link.",
"type": "string"
}
]
},
"CapabilityId": {
"description": "A stable, globally meaningful identity: a namespace, a dot, and a local part.\n`repository.info` and `objects.get` for executables; `<kind>.<identity>` for a\ndeclarative object (`rule.majordomus.scope-integrity@1`, `document.docs/CLI.md`,\n`policy..ai/repo/policy.yaml`).\n\nGrammar: the namespace matches `[a-z][a-z0-9_-]*`; the local part is non-empty and\ncarries no whitespace or control character, any other Unicode included, because it is\nopaque: a path, a versioned identity, or a name, as the kind's identity rule produced it.",
"type": "string"
},
"CapabilityKind": {
"description": "What a capability is. Three kinds exist because three semantics exist: something that\nis executed and changes nothing, something that is executed and changes this process's\nown memory, and something that is read. Nothing of any kind writes to the repository.\n\nHow *long* a call takes is not a kind. A read that walks every file of the layer is\nstill a read, and the thing that makes it worth watching — that it reports as it goes\nand stops when it is asked to — is one property of its handler, declared with\n[`crate::capability::Executable::cancellable`] and carried on [`ExecutionPolicy`].",
"oneOf": [
{
"const": "query",
"description": "Executable and read-only: a typed handler, an input schema, an output schema.",
"type": "string"
},
{
"const": "command",
"description": "Executable with an effect on this process's in-memory state and nowhere else (a\npeer announcing itself): a typed handler, bound to `POST` over HTTP, and announced\nto MCP clients as not read-only.",
"type": "string"
},
{
"const": "resource",
"description": "Declarative content the repository holds: read as it is, never executed.",
"type": "string"
}
]
},
"CapabilityProvenance": {
"description": "Where a capability came from. Never an absolute path.",
"oneOf": [
{
"description": "Written in Rust, in the named module of this executable.\nWritten in Rust, composed in `builtin.rs`.",
"properties": {
"module": {
"description": "The Rust module the descriptor was composed in.",
"type": "string"
},
"source": {
"const": "builtin",
"type": "string"
}
},
"required": [
"source",
"module"
],
"type": "object"
},
{
"description": "Read from the repository's layer.",
"properties": {
"directory": {
"description": "The directory the path sits in, repository-relative; `.` for the root.",
"type": "string"
},
"media_type": {
"description": "IANA media type of the object's content.",
"type": "string"
},
"member": {
"description": "For one member of a collection file, its key path in the file (`claims.3`).",
"type": [
"string",
"null"
]
},
"path": {
"description": "Repository-relative path.",
"type": "string"
},
"section": {
"description": "The manifest section the path falls under, when it falls under one.",
"type": [
"string",
"null"
]
},
"source": {
"const": "declarative",
"type": "string"
},
"source_class": {
"description": "The `sources.yaml` class that discovered the file.",
"type": "string"
}
},
"required": [
"source",
"path",
"directory",
"source_class",
"media_type"
],
"type": "object"
}
]
},
"CapabilityVisibility": {
"description": "Who a capability is for, and whether anything offers it.\n\nInternal is a statement, not an omission: a capability nothing projects is invisible\neither way, and the difference between deliberate and forgotten is exactly what this\nrecords.",
"oneOf": [
{
"const": "public",
"description": "Offered to anyone who can reach the process: an HTTP route or an MCP entry.",
"type": "string"
},
{
"const": "developer",
"description": "Offered to whoever runs the executable, and to nobody over a network.",
"type": "string"
},
{
"const": "internal",
"description": "Projected nowhere. It exists, it is listed as existing, and no surface offers it.",
"type": "string"
}
]
},
"CliExposure": {
"description": "How a capability appears on the command line: the words after `majordomus`.",
"properties": {
"path": {
"description": "The words after `majordomus`, e.g. `[\"capabilities\", \"list\"]`.",
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"path"
],
"type": "object"
},
"ExecutionConcurrency": {
"description": "Whether two executions of one capability may overlap.",
"oneOf": [
{
"const": "unrestricted",
"description": "Any number at once. Every read is one of these: the index and the registry are\nimmutable for the life of the process, so concurrent readers cannot interfere.",
"type": "string"
},
{
"const": "serial",
"description": "One at a time. A second execution of the same capability waits for the first, which\nis what a capability that changes anything — this process's own memory included —\nneeds in order to be reasoned about at all.",
"type": "string"
}
]
},
"ExecutionEffect": {
"description": "What running a capability changes outside the caller.\n\nClassified, never declared: it follows from the kind, which is the field a declaration\nalready carries. A projection reads this to decide whether to ask before running\nsomething — the Cockpit's confirmation is derived from it — instead of naming\ncapabilities it must treat carefully, which is a list that goes stale the day after it\nis written.",
"oneOf": [
{
"const": "read",
"description": "Nothing changes. Every query and every resource of this executable.",
"type": "string"
},
{
"const": "process_state",
"description": "This process's own memory changes, and nothing outside it.",
"type": "string"
},
{
"const": "repository_mutation",
"description": "The repository changes.\n\nNothing classifies to this, and the doctrine of this tool is why: no capability of\nany kind writes to the repository. It is on the model so that the day one does, it\nsays so here — where a projection already reads it and a client already asks before\nrunning it — rather than in whichever page happens to render its button.",
"type": "string"
}
]
},
"ExecutionPolicy": {
"description": "What running a capability as an execution means: what it changes, whether asking it to\nstop achieves anything, and whether two of them may overlap.\n\nThe effect and the concurrency are classified from the kind by\n[`ExecutionPolicy::classify`], for the same reason [`Availability`] is: the facts are\nalready on the declaration, and asking each `capability!` block to restate them would be\none more thing that can disagree with itself.\n\nCancellability is the one thing the kind cannot decide, because it is a fact about the\nhandler: whether it looks at its cancellation flag and stops. A handler that does says\nso with [`crate::capability::Executable::cancellable`], and a client is then told\nwhether a Cancel button will achieve anything instead of being given one that lies.",
"properties": {
"cancellable": {
"description": "Whether asking it to stop does anything. A task looks at its cancellation flag; a\nquery and a command do not, and a client is told so rather than being given a\nbutton that lies.",
"type": "boolean"
},
"concurrency": {
"$ref": "#/$defs/ExecutionConcurrency",
"description": "Whether two of them may overlap."
},
"effect": {
"$ref": "#/$defs/ExecutionEffect",
"description": "What it changes."
}
},
"required": [
"effect",
"cancellable",
"concurrency"
],
"type": "object"
},
"Exposure": {
"description": "The projections a capability declares. Absence is explicit: `None` means not exposed\nthere, and nothing infers an exposure a descriptor did not declare.",
"properties": {
"cli": {
"anyOf": [
{
"$ref": "#/$defs/CliExposure"
},
{
"type": "null"
}
],
"description": "The command-line projection, when declared."
},
"http": {
"anyOf": [
{
"$ref": "#/$defs/HttpExposure"
},
{
"type": "null"
}
],
"description": "The HTTP projection, when declared."
},
"mcp": {
"anyOf": [
{
"$ref": "#/$defs/McpExposure"
},
{
"type": "null"
}
],
"description": "The MCP projection, when declared."
}
},
"type": "object"
},
"HttpExposure": {
"description": "How a capability appears over HTTP. `GET` binds every top-level input property as a\nquery parameter; `POST` binds the input as the JSON request body. Paths are absolute\nand live under [`HttpExposure::PREFIX`].",
"properties": {
"method": {
"$ref": "#/$defs/HttpMethod",
"description": "The method."
},
"path": {
"description": "The absolute path, under [`HttpExposure::PREFIX`].",
"type": "string"
}
},
"required": [
"method",
"path"
],
"type": "object"
},
"HttpMethod": {
"description": "The HTTP methods a capability may be bound to.",
"oneOf": [
{
"const": "GET",
"description": "Read-only; the input is bound from the query string.",
"type": "string"
},
{
"const": "POST",
"description": "The input is bound from the JSON body. No builtin uses it yet.",
"type": "string"
}
]
},
"McpExposure": {
"description": "How, if at all, a capability appears to an MCP client.",
"properties": {
"resource": {
"anyOf": [
{
"$ref": "#/$defs/McpResource"
},
{
"type": "null"
}
],
"description": "As a readable resource."
},
"tool": {
"description": "As a tool with this name (`[a-z0-9_]+`).",
"type": [
"string",
"null"
]
}
},
"type": "object"
},
"McpResource": {
"description": "An MCP resource: its URI and the short name a client lists.",
"properties": {
"name": {
"description": "The short name a client lists; the identity for a declarative object.",
"type": "string"
},
"uri": {
"description": "`majordomus://<kind>/<identity>`, or `majordomus://repository`.",
"type": "string"
}
},
"required": [
"uri",
"name"
],
"type": "object"
},
"ModuleId": {
"description": "A module identity: the namespace of every capability the module composes, matching\n`[a-z][a-z0-9_-]*`. Builtin modules declare theirs in `module!`; a declarative\nobject's module is its kind.",
"type": "string"
},
"Stability": {
"description": "Where a capability stands, in the repository's own vocabulary for claims. A capability\nthat is `Planned` or `Unsupported` may be listed but is never executable through any\nprojection; the registry refuses to build otherwise.",
"oneOf": [
{
"const": "implemented",
"description": "Implemented, and no behavioural test names it yet.",
"type": "string"
},
{
"const": "behaviorally_verified",
"description": "Implemented and proved by a behavioural test.",
"type": "string"
},
{
"const": "experimental",
"description": "Implemented, executable, and expected to change.",
"type": "string"
},
{
"const": "planned",
"description": "Specified and not implemented: listed, never executable.",
"type": "string"
},
{
"const": "unsupported",
"description": "Considered and refused: listed with the reason, never executable.",
"type": "string"
}
]
},
"WaiverReason": {
"description": "Why an executable capability is not benchmarked. Typed, so that a waiver is a\nreviewable statement and never a convenience; `not_executable` is the registry's own\nreason for resources and is never written by hand.",
"oneOf": [
{
"const": "not_executable",
"description": "A resource: read, never executed; nothing to time but `objects.get`, which is.",
"type": "string"
},
{
"const": "destructive",
"description": "The capability changes something outside this process and cannot be run in a loop.",
"type": "string"
},
{
"const": "external_dependency",
"description": "The capability talks to something the benchmark host cannot provide.",
"type": "string"
},
{
"const": "transient_state",
"description": "The capability starts, or answers about, work that exists only while it is running.\nA benchmark host cannot stage an execution to read, and running the operation in a\nloop would measure the work rather than the operation.",
"type": "string"
}
]
}
},
"description": "The canonical descriptor. Everything a projection may say about a capability is here.",
"properties": {
"availability": {
"$ref": "#/$defs/CapabilityAvailability",
"description": "Where it means anything: classified from the kind and the transports above, so\nthat a projection reads a field instead of deciding for itself."
},
"benchmark": {
"$ref": "#/$defs/BenchmarkPolicy",
"description": "Whether it is a benchmark target; the cases come from the input type."
},
"cache": {
"$ref": "#/$defs/CachePolicy",
"description": "Whether the executor keeps its results."
},
"description": {
"description": "The one-paragraph description every projection shows.",
"type": "string"
},
"execution": {
"$ref": "#/$defs/ExecutionPolicy",
"description": "What running it as an execution means: classified from the kind, so that a client\nreads a fact rather than deciding for itself."
},
"exposure": {
"$ref": "#/$defs/Exposure",
"description": "Where it is projected; absence is explicit."
},
"id": {
"$ref": "#/$defs/CapabilityId",
"description": "The canonical identity."
},
"input": {
"$ref": "#/$defs/CanonicalSchema",
"description": "The canonical schema of the input; an empty object for a resource."
},
"kind": {
"$ref": "#/$defs/CapabilityKind",
"description": "Query, command or resource."
},
"module": {
"$ref": "#/$defs/ModuleId",
"description": "The module that composes it: the id's namespace for a builtin, the kind for a\ndeclarative object."
},
"output": {
"$ref": "#/$defs/CanonicalSchema",
"description": "The canonical schema of the output; the object view for a resource."
},
"provenance": {
"$ref": "#/$defs/CapabilityProvenance",
"description": "Where it came from."
},
"stability": {
"$ref": "#/$defs/Stability",
"description": "Where it stands."
},
"tags": {
"description": "Free tags, from the declarative object's `tags` or the descriptor.",
"items": {
"type": "string"
},
"type": "array"
},
"title": {
"description": "The short name every projection shows.",
"type": "string"
},
"visibility": {
"$ref": "#/$defs/CapabilityVisibility",
"description": "Who it is for: classified from the same transports."
}
},
"required": [
"id",
"module",
"kind",
"title",
"description",
"input",
"output",
"provenance",
"exposure",
"availability",
"visibility",
"stability",
"benchmark",
"cache",
"execution"
],
"title": "Capability",
"type": "object"
}Policies
- benchmark
- required — a target on every transport the exposure declares; the cases are the input type's
- cache
- disabled — every call runs the handler
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.
| transport | state | cases | targets |
|---|---|---|---|
| direct | covered | 1 | repository-info |
| mcp | covered | 1 | repository-info |
| http | covered | 1 | repository-info |