capabilities.describe

{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "id": {
      "type": "string",
      "description": "The canonical id, e.g. `repository.info` or `rule.majordomus.scope-integrity@1`."
    }
  },
  "required": [
    "id"
  ],
  "description": "The input of `capabilities.describe`: which capability.",
  "title": "DescribeInput"
}

{
  "type": "object",
  "properties": {
    "id": {
      "$ref": "#/$defs/CapabilityId",
      "description": "The canonical identity."
    },
    "module": {
      "$ref": "#/$defs/ModuleId",
      "description": "The module that composes it: the id's namespace for a builtin, the kind for a\ndeclarative object."
    },
    "kind": {
      "$ref": "#/$defs/CapabilityKind",
      "description": "Query, command or resource."
    },
    "title": {
      "type": "string",
      "description": "The short name every projection shows."
    },
    "description": {
      "type": "string",
      "description": "The one-paragraph description every projection shows."
    },
    "input": {
      "$ref": "#/$defs/CanonicalSchema",
      "description": "The canonical schema of the input; an empty object for a resource."
    },
    "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."
    },
    "exposure": {
      "$ref": "#/$defs/Exposure",
      "description": "Where it is projected; absence is explicit."
    },
    "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."
    },
    "visibility": {
      "$ref": "#/$defs/CapabilityVisibility",
      "description": "Who it is for: classified from the same transports."
    },
    "stability": {
      "$ref": "#/$defs/Stability",
      "description": "Where it stands."
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Free tags, from the declarative object's `tags` or the descriptor."
    },
    "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."
    },
    "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."
    },
    "skill": {
      "anyOf": [
        {
          "$ref": "#/$defs/SkillExposure"
        },
        {
          "type": "null"
        }
      ],
      "description": "The short name a person invokes it by from an agent's prompt, when it has one."
    }
  },
  "required": [
    "id",
    "module",
    "kind",
    "title",
    "description",
    "input",
    "output",
    "provenance",
    "exposure",
    "availability",
    "visibility",
    "stability",
    "benchmark",
    "cache",
    "execution"
  ],
  "description": "The canonical descriptor. Everything a projection may say about a capability is here.",
  "title": "Capability",
  "$defs": {
    "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`."
    },
    "CanonicalSchema": {
      "type": "object",
      "properties": {
        "name": {
          "type": [
            "string",
            "null"
          ],
          "description": "The component name projections use (`RepositoryInfo`); `None` for an anonymous\nschema such as the empty input."
        },
        "schema": {
          "description": "The schema itself, without `$schema`; nested types live under `$defs`."
        }
      },
      "required": [
        "schema"
      ],
      "description": "A JSON Schema with, when the type has one, a stable component name (the type's title)."
    },
    "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`."
    },
    "CapabilityAvailability": {
      "oneOf": [
        {
          "type": "string",
          "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."
        }
      ],
      "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."
    },
    "CapabilityVisibility": {
      "oneOf": [
        {
          "type": "string",
          "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."
        }
      ],
      "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."
    },
    "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`)."
    },
    "ExecutionPolicy": {
      "type": "object",
      "properties": {
        "effect": {
          "$ref": "#/$defs/ExecutionEffect",
          "description": "What it changes."
        },
        "cancellable": {
          "type": "boolean",
          "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."
        },
        "concurrency": {
          "$ref": "#/$defs/ExecutionConcurrency",
          "description": "Whether two of them may overlap."
        },
        "signed_input": {
          "type": "boolean",
          "description": "Whether the input authenticates its caller.\n\nA handler whose input is a signed message, and which verifies the signature against\nthe trust policy before anything changes, admits its caller by that signature and not\nby the address the request came from. Only such a handler changes state for a caller\non another host; see `ExecutionPolicy::admits_remote`."
        }
      },
      "required": [
        "effect",
        "cancellable",
        "concurrency"
      ],
      "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."
    },
    "ExecutionEffect": {
      "oneOf": [
        {
          "type": "string",
          "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\nFor most of this executable's life nothing classified to this, because no capability\nof any kind wrote to the repository. That day arrived with [ADR 0040]: development\nsemantics are capabilities of this runtime, and the first of them — `plan.transition`\n— stamps a field into an issue's own tracked record. The variant was put on the model\nin advance so that when one did, it would say so *here*, where a projection already\nreads it and a client already asks before running it, rather than in whichever page\nhappens to render its button.\n\nIt is not classified from the kind, because the kind cannot know it: a command that\nannounces a peer and a command that writes a tracked file are the same kind. A\nhandler that writes the repository says so with\n`ExecutionPolicy::writes_repository`, the way one that stops says so with\n`ExecutionPolicy::stoppable`.\n\n[ADR 0040]: https://github.com/korczis/prismatic-majordomus/blob/master/.ai/repo/adrs/0040-development-semantics-are-capabilities-of-one-runtime.md"
        }
      ],
      "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."
    },
    "ExecutionConcurrency": {
      "oneOf": [
        {
          "type": "string",
          "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."
        }
      ],
      "description": "Whether two executions of one capability may overlap."
    },
    "SkillExposure": {
      "type": "object",
      "properties": {
        "alias": {
          "type": "string",
          "description": "The name typed after the slash: lowercase letters, digits and hyphens, at most 64."
        },
        "argument": {
          "type": "string",
          "description": "The input field the text typed after the name fills, verbatim."
        }
      },
      "required": [
        "alias",
        "argument"
      ],
      "description": "A capability as a skill a person invokes by a short name from an agent's prompt:\n`/intent <sentence>` in Claude Code. The name and the one input field the typed text\nfills are declared here, once; the file an agent product reads is generated from them\n(the `editors` module) and carries no description of what the capability does beyond\nthe capability's own.\n\n```\nuse majordomus_cli::capability::SkillExposure;\nlet s = SkillExposure { alias: \"intent\".into(), argument: \"statement\".into() };\nassert!(s.validate().is_ok());\n// a name an agent product already owns is refused, and so is one that is not a name\nlet taken = SkillExposure { alias: \"review\".into(), argument: \"x\".into() };\nassert!(taken.validate().unwrap_err().contains(\"reserved\"));\nlet shouted = SkillExposure { alias: \"Intent\".into(), argument: \"x\".into() };\nassert!(shouted.validate().is_err());\n```"
    }
  }
}