capabilities.list
Every capability of this executable and this repository, summarised: kind, module, stability, provenance, the projections it declares, its benchmark and cache policy; the schemas are answered by capabilities.describe.
Every capability of this executable and this repository, summarised: kind, module, stability, provenance, the projections it declares, its benchmark and cache policy; the schemas are answered by capabilities.describe.
- 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_capabilities |
| HTTP | GET /api/v1/capabilities operationId capabilities.list |
| command line | majordomus capabilities list |
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 · CapabilitiesInput
The input of `capabilities.list`: optional filters by kind and by projection.
| property | type | required | description |
|---|---|---|---|
| exposure | string | null | no | Only capabilities exposed through this projection: `mcp`, `http` or `cli`. default null |
| kind | string | null | no | Only capabilities of this kind: `query`, `command` or `resource`. default null |
JSON Schema
{
"additionalProperties": false,
"description": "The input of `capabilities.list`: optional filters by kind and by projection.",
"properties": {
"exposure": {
"default": null,
"description": "Only capabilities exposed through this projection: `mcp`, `http` or `cli`.",
"type": [
"string",
"null"
]
},
"kind": {
"default": null,
"description": "Only capabilities of this kind: `query`, `command` or `resource`.",
"type": [
"string",
"null"
]
}
},
"title": "CapabilitiesInput",
"type": "object"
}output · CapabilityList
The answer of `capabilities.list`: the matching capabilities, summarised, and the registry counted.
| property | type | required | description |
|---|---|---|---|
| capabilities | array | yes | The matching capabilities, by id, without their schemas. |
| count | integer | yes | How many capabilities matched the filters. |
| summary | reference | yes | The whole registry, counted by kind, stability and projection. |
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"
}
]
},
"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"
}
]
},
"CapabilitySummary": {
"description": "One capability as a listing shows it: everything the descriptor says except its two\nschemas, which `capabilities.describe` answers for one capability. A listing of a\nrepository's registry runs to hundreds of entries; their schemas would be megabytes\nof the same object view repeated.",
"properties": {
"benchmark": {
"$ref": "#/$defs/BenchmarkPolicy",
"description": "Whether it is a benchmark target."
},
"cache": {
"$ref": "#/$defs/CachePolicy",
"description": "Whether the executor keeps its results."
},
"description": {
"description": "The one-paragraph description.",
"type": "string"
},
"exposure": {
"$ref": "#/$defs/Exposure",
"description": "Where it is projected."
},
"id": {
"$ref": "#/$defs/CapabilityId",
"description": "The canonical identity."
},
"kind": {
"$ref": "#/$defs/CapabilityKind",
"description": "Query, command or resource."
},
"module": {
"$ref": "#/$defs/ModuleId",
"description": "The module that composes it."
},
"provenance": {
"$ref": "#/$defs/CapabilityProvenance",
"description": "Where it came from."
},
"stability": {
"$ref": "#/$defs/Stability",
"description": "Where it stands."
},
"tags": {
"description": "Free tags.",
"items": {
"type": "string"
},
"type": "array"
},
"title": {
"description": "The short name.",
"type": "string"
}
},
"required": [
"id",
"module",
"kind",
"title",
"description",
"provenance",
"exposure",
"stability",
"benchmark",
"cache"
],
"type": "object"
},
"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"
},
"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"
}
]
},
"Summary": {
"description": "The registry counted: by source, kind, stability and projection.",
"properties": {
"benchmark_required": {
"description": "Executables whose benchmark policy is required.",
"format": "uint",
"minimum": 0,
"type": "integer"
},
"benchmark_waived": {
"description": "Executables waived from benchmarking for a typed reason.",
"format": "uint",
"minimum": 0,
"type": "integer"
},
"builtin": {
"description": "Composed in Rust.",
"format": "uint",
"minimum": 0,
"type": "integer"
},
"by_kind": {
"additionalProperties": {
"format": "uint",
"minimum": 0,
"type": "integer"
},
"description": "By kind (`query`, `resource`).",
"type": "object"
},
"by_stability": {
"additionalProperties": {
"format": "uint",
"minimum": 0,
"type": "integer"
},
"description": "By stability.",
"type": "object"
},
"cached": {
"description": "Executables the executor caches.",
"format": "uint",
"minimum": 0,
"type": "integer"
},
"cli_commands": {
"description": "With a CLI exposure.",
"format": "uint",
"minimum": 0,
"type": "integer"
},
"declarative": {
"description": "Read from the layer.",
"format": "uint",
"minimum": 0,
"type": "integer"
},
"http_routes": {
"description": "With an HTTP exposure.",
"format": "uint",
"minimum": 0,
"type": "integer"
},
"mcp_resources": {
"description": "With an MCP resource exposure.",
"format": "uint",
"minimum": 0,
"type": "integer"
},
"mcp_tools": {
"description": "With an MCP tool exposure.",
"format": "uint",
"minimum": 0,
"type": "integer"
},
"modules": {
"description": "Modules: composed, derived, and one per declarative kind.",
"format": "uint",
"minimum": 0,
"type": "integer"
},
"total": {
"description": "Every capability.",
"format": "uint",
"minimum": 0,
"type": "integer"
}
},
"required": [
"total",
"builtin",
"declarative",
"by_kind",
"by_stability",
"mcp_tools",
"mcp_resources",
"http_routes",
"cli_commands",
"modules",
"benchmark_required",
"benchmark_waived",
"cached"
],
"type": "object"
},
"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 answer of `capabilities.list`: the matching capabilities, summarised, and the\nregistry counted.",
"properties": {
"capabilities": {
"description": "The matching capabilities, by id, without their schemas.",
"items": {
"$ref": "#/$defs/CapabilitySummary"
},
"type": "array"
},
"count": {
"description": "How many capabilities matched the filters.",
"format": "uint",
"minimum": 0,
"type": "integer"
},
"summary": {
"$ref": "#/$defs/Summary",
"description": "The whole registry, counted by kind, stability and projection."
}
},
"required": [
"count",
"summary",
"capabilities"
],
"title": "CapabilityList",
"type": "object"
}Policies
- benchmark
- required — a target on every transport the exposure declares; the cases are the input type's
- cache
- process — up to 16 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.
The moments this answers
- shipped an interface change whose contract document still described the old one A contract maintained by hand beside the code it describes goes stale on the first change that forgets it.
- pasted a command from the documentation and watched it fail Examples are written once, in prose, and nothing ever executes them again.
- had a green pipeline over generated files that no longer matched their sources Tests exercise the code and say nothing about the committed outputs derived from it, so the build is green and the artifacts are wrong.