capabilities.list

{
  "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"
}

{
  "$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": "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.",
          "properties": {
            "policy": {
              "const": "required_when",
              "type": "string"
            },
            "precondition": {
              "$ref": "#/$defs/BenchmarkPrecondition",
              "description": "What the repository must hold."
            }
          },
          "required": [
            "policy",
            "precondition"
          ],
          "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"
        }
      ]
    },
    "BenchmarkPrecondition": {
      "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```",
      "oneOf": [
        {
          "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.",
          "type": "string"
        }
      ]
    },
    "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. 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`).",
      "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"
        },
        {
          "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.",
          "properties": {
            "max_entries": {
              "description": "The most entries kept for this capability; the oldest is evicted first.",
              "format": "uint",
              "minimum": 0,
              "type": "integer"
            },
            "policy": {
              "const": "generation",
              "type": "string"
            }
          },
          "required": [
            "policy",
            "max_entries"
          ],
          "type": "object"
        },
        {
          "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.",
          "properties": {
            "max_entries": {
              "description": "The most entries kept for this capability; the oldest is evicted first.",
              "format": "uint",
              "minimum": 0,
              "type": "integer"
            },
            "policy": {
              "const": "checkout",
              "type": "string"
            }
          },
          "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. 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`.",
      "oneOf": [
        {
          "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.",
          "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. Every mutating capability uses it.",
          "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"
        },
        {
          "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.",
          "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"
}