capabilities.list

{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "kind": {
      "type": [
        "string",
        "null"
      ],
      "description": "Only capabilities of this kind: `query`, `command` or `resource`.",
      "default": null
    },
    "exposure": {
      "type": [
        "string",
        "null"
      ],
      "description": "Only capabilities exposed through this projection: `mcp`, `http` or `cli`.",
      "default": null
    }
  },
  "description": "The input of `capabilities.list`: optional filters by kind and by projection.",
  "title": "CapabilitiesInput"
}

{
  "type": "object",
  "properties": {
    "count": {
      "type": "integer",
      "format": "uint",
      "minimum": 0,
      "description": "How many capabilities matched the filters."
    },
    "summary": {
      "$ref": "#/$defs/Summary",
      "description": "The whole registry, counted by kind, stability and projection."
    },
    "capabilities": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/CapabilitySummary"
      },
      "description": "The matching capabilities, by id, without their schemas."
    }
  },
  "required": [
    "count",
    "summary",
    "capabilities"
  ],
  "description": "The answer of `capabilities.list`: the matching capabilities, summarised, and the\nregistry counted.",
  "title": "CapabilityList",
  "$defs": {
    "Summary": {
      "type": "object",
      "properties": {
        "total": {
          "type": "integer",
          "format": "uint",
          "minimum": 0,
          "description": "Every capability."
        },
        "builtin": {
          "type": "integer",
          "format": "uint",
          "minimum": 0,
          "description": "Composed in Rust."
        },
        "declarative": {
          "type": "integer",
          "format": "uint",
          "minimum": 0,
          "description": "Read from the layer."
        },
        "by_kind": {
          "type": "object",
          "additionalProperties": {
            "type": "integer",
            "format": "uint",
            "minimum": 0
          },
          "description": "By kind (`query`, `resource`)."
        },
        "by_stability": {
          "type": "object",
          "additionalProperties": {
            "type": "integer",
            "format": "uint",
            "minimum": 0
          },
          "description": "By stability."
        },
        "mcp_tools": {
          "type": "integer",
          "format": "uint",
          "minimum": 0,
          "description": "With an MCP tool exposure."
        },
        "mcp_resources": {
          "type": "integer",
          "format": "uint",
          "minimum": 0,
          "description": "With an MCP resource exposure."
        },
        "http_routes": {
          "type": "integer",
          "format": "uint",
          "minimum": 0,
          "description": "With an HTTP exposure."
        },
        "cli_commands": {
          "type": "integer",
          "format": "uint",
          "minimum": 0,
          "description": "With a CLI exposure."
        },
        "modules": {
          "type": "integer",
          "format": "uint",
          "minimum": 0,
          "description": "Modules: composed, derived, and one per declarative kind."
        },
        "benchmark_required": {
          "type": "integer",
          "format": "uint",
          "minimum": 0,
          "description": "Executables whose benchmark policy is required."
        },
        "benchmark_waived": {
          "type": "integer",
          "format": "uint",
          "minimum": 0,
          "description": "Executables waived from benchmarking for a typed reason."
        },
        "cached": {
          "type": "integer",
          "format": "uint",
          "minimum": 0,
          "description": "Executables the executor caches."
        }
      },
      "required": [
        "total",
        "builtin",
        "declarative",
        "by_kind",
        "by_stability",
        "mcp_tools",
        "mcp_resources",
        "http_routes",
        "cli_commands",
        "modules",
        "benchmark_required",
        "benchmark_waived",
        "cached"
      ],
      "description": "The registry counted: by source, kind, stability and projection."
    },
    "CapabilitySummary": {
      "type": "object",
      "properties": {
        "id": {
          "$ref": "#/$defs/CapabilityId",
          "description": "The canonical identity."
        },
        "module": {
          "$ref": "#/$defs/ModuleId",
          "description": "The module that composes it."
        },
        "kind": {
          "$ref": "#/$defs/CapabilityKind",
          "description": "Query, command or resource."
        },
        "title": {
          "type": "string",
          "description": "The short name."
        },
        "description": {
          "type": "string",
          "description": "The one-paragraph description."
        },
        "provenance": {
          "$ref": "#/$defs/CapabilityProvenance",
          "description": "Where it came from."
        },
        "exposure": {
          "$ref": "#/$defs/Exposure",
          "description": "Where it is projected."
        },
        "stability": {
          "$ref": "#/$defs/Stability",
          "description": "Where it stands."
        },
        "tags": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Free tags."
        },
        "benchmark": {
          "$ref": "#/$defs/BenchmarkPolicy",
          "description": "Whether it is a benchmark target."
        },
        "cache": {
          "$ref": "#/$defs/CachePolicy",
          "description": "Whether the executor keeps its results."
        }
      },
      "required": [
        "id",
        "module",
        "kind",
        "title",
        "description",
        "provenance",
        "exposure",
        "stability",
        "benchmark",
        "cache"
      ],
      "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."
    },
    "CapabilityId": {
      "type": "string",
      "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."
    },
    "ModuleId": {
      "type": "string",
      "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."
    },
    "CapabilityKind": {
      "oneOf": [
        {
          "type": "string",
          "const": "query",
          "description": "Executable and read-only: a typed handler, an input schema, an output schema."
        },
        {
          "type": "string",
          "const": "command",
          "description": "Executable and changing something: a typed handler, bound to `POST` over HTTP, and\nannounced to MCP clients as not read-only. Most reach no further than this process's\nown memory (a peer announcing itself); one that writes the repository's tracked\nrecords says so on its execution policy, which is where a projection reads it."
        },
        {
          "type": "string",
          "const": "resource",
          "description": "Declarative content the repository holds: read as it is, never executed."
        }
      ],
      "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. A command may also write the repository's own\ntracked records, which its kind does not say and its execution policy does\n(`ExecutionPolicy::writes_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`."
    },
    "CapabilityProvenance": {
      "oneOf": [
        {
          "type": "object",
          "properties": {
            "module": {
              "type": "string",
              "description": "The Rust module the descriptor was composed in."
            },
            "source": {
              "type": "string",
              "const": "builtin"
            }
          },
          "required": [
            "source",
            "module"
          ],
          "description": "Written in Rust, in the named module of this executable.\nWritten in Rust, composed in `builtin.rs`."
        },
        {
          "type": "object",
          "properties": {
            "path": {
              "type": "string",
              "description": "Repository-relative path."
            },
            "directory": {
              "type": "string",
              "description": "The directory the path sits in, repository-relative; `.` for the root."
            },
            "source_class": {
              "type": "string",
              "description": "The `sources.yaml` class that discovered the file."
            },
            "section": {
              "type": [
                "string",
                "null"
              ],
              "description": "The manifest section the path falls under, when it falls under one."
            },
            "media_type": {
              "type": "string",
              "description": "IANA media type of the object's content."
            },
            "member": {
              "type": [
                "string",
                "null"
              ],
              "description": "For one member of a collection file, its key path in the file (`claims.3`)."
            },
            "source": {
              "type": "string",
              "const": "declarative"
            }
          },
          "required": [
            "source",
            "path",
            "directory",
            "source_class",
            "media_type"
          ],
          "description": "Read from the repository's layer."
        }
      ],
      "description": "Where a capability came from. Never an absolute path."
    },
    "Exposure": {
      "type": "object",
      "properties": {
        "mcp": {
          "anyOf": [
            {
              "$ref": "#/$defs/McpExposure"
            },
            {
              "type": "null"
            }
          ],
          "description": "The MCP projection, when declared."
        },
        "http": {
          "anyOf": [
            {
              "$ref": "#/$defs/HttpExposure"
            },
            {
              "type": "null"
            }
          ],
          "description": "The HTTP projection, when declared."
        },
        "cli": {
          "anyOf": [
            {
              "$ref": "#/$defs/CliExposure"
            },
            {
              "type": "null"
            }
          ],
          "description": "The command-line projection, when declared."
        }
      },
      "description": "The projections a capability declares. Absence is explicit: `None` means not exposed\nthere, and nothing infers an exposure a descriptor did not declare."
    },
    "McpExposure": {
      "type": "object",
      "properties": {
        "tool": {
          "type": [
            "string",
            "null"
          ],
          "description": "As a tool with this name (`[a-z0-9_]+`)."
        },
        "resource": {
          "anyOf": [
            {
              "$ref": "#/$defs/McpResource"
            },
            {
              "type": "null"
            }
          ],
          "description": "As a readable resource."
        }
      },
      "description": "How, if at all, a capability appears to an MCP client."
    },
    "McpResource": {
      "type": "object",
      "properties": {
        "uri": {
          "type": "string",
          "description": "`majordomus://<kind>/<identity>`, or `majordomus://repository`."
        },
        "name": {
          "type": "string",
          "description": "The short name a client lists; the identity for a declarative object."
        }
      },
      "required": [
        "uri",
        "name"
      ],
      "description": "An MCP resource: its URI and the short name a client lists."
    },
    "HttpExposure": {
      "type": "object",
      "properties": {
        "method": {
          "$ref": "#/$defs/HttpMethod",
          "description": "The method."
        },
        "path": {
          "type": "string",
          "description": "The absolute path, under `HttpExposure::PREFIX`."
        }
      },
      "required": [
        "method",
        "path"
      ],
      "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`."
    },
    "HttpMethod": {
      "oneOf": [
        {
          "type": "string",
          "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. Every mutating capability uses it."
        }
      ],
      "description": "The HTTP methods a capability may be bound to."
    },
    "CliExposure": {
      "type": "object",
      "properties": {
        "path": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "The words after `majordomus`, e.g. `[\"capabilities\", \"list\"]`."
        }
      },
      "required": [
        "path"
      ],
      "description": "How a capability appears on the command line: the words after `majordomus`."
    },
    "Stability": {
      "oneOf": [
        {
          "type": "string",
          "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."
        }
      ],
      "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."
    },
    "BenchmarkPolicy": {
      "oneOf": [
        {
          "type": "object",
          "properties": {
            "policy": {
              "type": "string",
              "const": "required"
            }
          },
          "required": [
            "policy"
          ],
          "description": "Timed directly and through every exposure; coverage fails without a case."
        },
        {
          "type": "object",
          "properties": {
            "precondition": {
              "$ref": "#/$defs/BenchmarkPrecondition",
              "description": "What the repository must hold."
            },
            "policy": {
              "type": "string",
              "const": "required_when"
            }
          },
          "required": [
            "policy",
            "precondition"
          ],
          "description": "Required exactly like `Required` in a repository where the precondition holds, and\nreported as inapplicable — never covered, never waived — where it does not. Not a\nwaiver: with the precondition met and no case, the requirement is missing."
        },
        {
          "type": "object",
          "properties": {
            "reason": {
              "$ref": "#/$defs/WaiverReason",
              "description": "Why."
            },
            "policy": {
              "type": "string",
              "const": "waived"
            }
          },
          "required": [
            "policy",
            "reason"
          ],
          "description": "Not timed, for the typed reason; coverage reports it as waived, never as covered."
        }
      ],
      "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."
    },
    "BenchmarkPrecondition": {
      "oneOf": [
        {
          "type": "string",
          "const": "plan_holds_an_issue",
          "description": "The plan holds at least one issue. A command whose every honest case is a refusal\nchosen from an issue's own status has no such refusal in a plan with no issue: the\nonly answer there is a lookup miss, which times an error path and is not the\noperation."
        }
      ],
      "description": "What a repository must hold before a conditional benchmark requirement applies to it.\nTyped, like a waiver's reason, so that the condition is a reviewable statement on the\ndescriptor and never a provider quietly returning nothing.\n\n```\nuse majordomus_cli::capability::BenchmarkPrecondition;\nlet p: BenchmarkPrecondition = serde_json::from_str(r#\"\"plan_holds_an_issue\"\"#).unwrap();\nassert_eq!(p, BenchmarkPrecondition::PlanHoldsAnIssue);\n```"
    },
    "WaiverReason": {
      "oneOf": [
        {
          "type": "string",
          "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",
          "const": "published_history",
          "description": "The capability answers about what this repository has *published*, so its input is a\nrelease: a version tag, the commit it points at, and the projection committed there.\nA benchmark fixture is a repository that has published nothing, and the honest answer\nin one is a refusal — so the case would time an error path and call it coverage.\nDistinct from `WaiverReason::ExternalDependency`: nothing outside this process is\nconsulted, and distinct from `WaiverReason::TransientState`: the history is durable,\nit simply does not exist yet where the benchmark runs."
        }
      ],
      "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."
    },
    "CachePolicy": {
      "oneOf": [
        {
          "type": "object",
          "properties": {
            "policy": {
              "type": "string",
              "const": "disabled"
            }
          },
          "required": [
            "policy"
          ],
          "description": "Every call runs the handler."
        },
        {
          "type": "object",
          "properties": {
            "max_entries": {
              "type": "integer",
              "format": "uint",
              "minimum": 0,
              "description": "The most entries kept for this capability; the oldest is evicted first."
            },
            "ttl_seconds": {
              "type": [
                "integer",
                "null"
              ],
              "format": "uint64",
              "minimum": 0,
              "description": "Seconds an entry stays valid; `None` for the life of the process."
            },
            "policy": {
              "type": "string",
              "const": "process"
            }
          },
          "required": [
            "policy",
            "max_entries"
          ],
          "description": "Results are kept in this process's memory, bounded, for equal inputs."
        },
        {
          "type": "object",
          "properties": {
            "max_entries": {
              "type": "integer",
              "format": "uint",
              "minimum": 0,
              "description": "The most entries kept for this capability; the oldest is evicted first."
            },
            "policy": {
              "type": "string",
              "const": "generation"
            }
          },
          "required": [
            "policy",
            "max_entries"
          ],
          "description": "Results are kept for equal inputs while the context that computed them is the one\nasked: for a capability that is a function of the index and the registry alone,\nincluding the git state the index was read at, which the registry fingerprint does\nnot cover. A reload of the repository is a new context, and so a new key."
        },
        {
          "type": "object",
          "properties": {
            "max_entries": {
              "type": "integer",
              "format": "uint",
              "minimum": 0,
              "description": "The most entries kept for this capability; the oldest is evicted first."
            },
            "policy": {
              "type": "string",
              "const": "checkout"
            }
          },
          "required": [
            "policy",
            "max_entries"
          ],
          "description": "Results are kept for equal inputs while the context is the same *and* the checkout\nis as it was: HEAD, the staging index, the refs and every changed or untracked path\nof the work tree, fingerprinted again on every call\n(`capability::checkout`). For a capability that reads git, the index and the\nfiles of the work tree, and nothing that fingerprint cannot see: no ignored file, no\nother process, no network, no clock. A checkout git cannot fingerprint is not cached."
        }
      ],
      "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. The two narrower policies add to the key\nwhat the registry fingerprint cannot see: the context's own reading of the repository\n(`CachePolicy::Generation`) and the state of the checkout itself\n(`CachePolicy::Checkout`)."
    }
  }
}