directories.list

Every directory of the layer the index knows, with the contract it declares, whether it owes one and which contract decided, and — for a named path, or when asked for everywhere — the effective chain composed from the root down, least specific first.

query
behaviorally_verified
module directories
#directories
#context
#introspection

Exposure

Where this one definition is reachable. Absence is explicit: a surface not listed does not carry it.

surface	as
MCP	tool majordomus_directories resource majordomus://directories
HTTP	GET /api/v1/directories operationId directories.list
command line	—

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 · DirectoriesInput

Which directories to answer for, and how much of the hierarchy to resolve.

property	type	required	description
effective	boolean \| null	no	Resolve the effective chain for every directory, not only for a named one.
path	string \| null	no	One directory, repository-relative and inside the layer. Its effective chain is always resolved. Absent means every directory of the layer.
state	one of 2	no	Only directories in this state: `documented`, `exempt` or `owed`.

JSON Schema

{
  "$defs": {
    "DirectoryState": {
      "description": "Whether a directory of the layer carries the contract it owes.",
      "oneOf": [
        {
          "const": "documented",
          "description": "It carries a context document of its own.",
          "type": "string"
        },
        {
          "const": "exempt",
          "description": "It owes none, because a contract above it says so.",
          "type": "string"
        },
        {
          "const": "owed",
          "description": "It owes one and has none.",
          "type": "string"
        }
      ]
    }
  },
  "additionalProperties": false,
  "description": "Which directories to answer for, and how much of the hierarchy to resolve.",
  "properties": {
    "effective": {
      "description": "Resolve the effective chain for every directory, not only for a named one.",
      "type": [
        "boolean",
        "null"
      ]
    },
    "path": {
      "description": "One directory, repository-relative and inside the layer. Its effective chain is\nalways resolved. Absent means every directory of the layer.",
      "type": [
        "string",
        "null"
      ]
    },
    "state": {
      "anyOf": [
        {
          "$ref": "#/$defs/DirectoryState"
        },
        {
          "type": "null"
        }
      ],
      "description": "Only directories in this state: `documented`, `exempt` or `owed`."
    }
  },
  "title": "DirectoriesInput",
  "type": "object"
}

output · DirectoryReport

The layer's directories, what each owes, and the contracts that apply.

property	type	required	description
directories	array	yes	Every directory asked for, sorted by path.
root	string	yes	The layer root the tree is rooted at.
tallies	reference	yes	The directories in each state.

JSON Schema

{
  "$defs": {
    "ContractView": {
      "description": "A directory contract as the document declares it, before anything is inherited.",
      "properties": {
        "audience": {
          "description": "Who it addresses; both when it says nothing.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "children_exempt": {
          "description": "Subtrees below this one that owe nothing: carried, not authored here.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "children_require_contract": {
          "description": "Whether the directories below owe a contract, when this document says.",
          "type": [
            "boolean",
            "null"
          ]
        },
        "composition": {
          "description": "`extend`, `replace` or `final`: how it composes with what is above it.",
          "type": "string"
        },
        "description": {
          "description": "One line saying what the directory is for.",
          "type": [
            "string",
            "null"
          ]
        },
        "id": {
          "description": "The document's identity; it survives a move, the file name does not.",
          "type": "string"
        },
        "order": {
          "description": "Ties within one depth are broken by this, then by path.",
          "format": "int64",
          "type": "integer"
        },
        "path": {
          "description": "The document's path, repository-relative.",
          "type": "string"
        },
        "providers": {
          "description": "`*`, or the providers the document is written for.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "scope": {
          "description": "`directory`, `subtree` or `explicit`: how far the document reaches.",
          "type": "string"
        },
        "status": {
          "description": "`active` or `deprecated`; a deprecated document is listed and never applied.",
          "type": "string"
        },
        "title": {
          "description": "One line naming the directory.",
          "type": [
            "string",
            "null"
          ]
        },
        "tracks": {
          "description": "Pathspecs whose change names this document for review.",
          "items": {
            "type": "string"
          },
          "type": "array"
        }
      },
      "required": [
        "id",
        "path",
        "status",
        "scope",
        "composition",
        "order",
        "providers",
        "audience"
      ],
      "type": "object"
    },
    "DirectoryNode": {
      "description": "One directory of the layer, what it owes, and what applies to it.",
      "properties": {
        "children": {
          "description": "The directories immediately below, sorted.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "contract": {
          "anyOf": [
            {
              "$ref": "#/$defs/ContractView"
            },
            {
              "type": "null"
            }
          ],
          "description": "The contract this directory declares, before inheritance."
        },
        "depth": {
          "description": "Segments below the layer root; the root itself is 0.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "effective": {
          "description": "The contracts that apply here once inheritance is resolved, least specific first.\nPresent when the request asked for it, or when it asked about one path.",
          "items": {
            "$ref": "#/$defs/EffectiveEntry"
          },
          "type": "array"
        },
        "exempted_by": {
          "description": "The contract that released this subtree, when one did.",
          "type": [
            "string",
            "null"
          ]
        },
        "governed_by": {
          "description": "The contract that made the requirement explicit, when one did.",
          "type": [
            "string",
            "null"
          ]
        },
        "objects": {
          "description": "How many objects of any kind the index holds directly in this directory.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "parent": {
          "description": "The directory above, when it is inside the layer.",
          "type": [
            "string",
            "null"
          ]
        },
        "path": {
          "description": "Repository-relative, forward slashes.",
          "type": "string"
        },
        "requires_contract": {
          "description": "Whether a contract is owed here at all.",
          "type": "boolean"
        },
        "state": {
          "$ref": "#/$defs/DirectoryState",
          "description": "Whether it carries the contract it owes."
        }
      },
      "required": [
        "path",
        "depth",
        "state",
        "requires_contract",
        "objects"
      ],
      "type": "object"
    },
    "DirectoryState": {
      "description": "Whether a directory of the layer carries the contract it owes.",
      "oneOf": [
        {
          "const": "documented",
          "description": "It carries a context document of its own.",
          "type": "string"
        },
        {
          "const": "exempt",
          "description": "It owes none, because a contract above it says so.",
          "type": "string"
        },
        {
          "const": "owed",
          "description": "It owes one and has none.",
          "type": "string"
        }
      ]
    },
    "DirectoryTallies": {
      "description": "How many directories are in each state.",
      "properties": {
        "directories": {
          "description": "Every directory of the layer the index knows.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "documented": {
          "description": "Carrying a contract of their own.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "exempt": {
          "description": "Released by a contract above them.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "owed": {
          "description": "Owing a contract and carrying none.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        }
      },
      "required": [
        "directories",
        "documented",
        "exempt",
        "owed"
      ],
      "type": "object"
    },
    "EffectiveEntry": {
      "description": "One contract in a directory's effective chain, in the order it is applied.",
      "properties": {
        "composition": {
          "description": "`extend`, `replace` or `final`.",
          "type": "string"
        },
        "depth": {
          "description": "Depth below the layer root; less is less specific and applies first.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "id": {
          "description": "The document's identity.",
          "type": "string"
        },
        "local": {
          "description": "True for the directory's own document, false for one it inherits.",
          "type": "boolean"
        },
        "order": {
          "description": "The declared order, the second sort key.",
          "format": "int64",
          "type": "integer"
        },
        "path": {
          "description": "The document's path.",
          "type": "string"
        },
        "reason": {
          "description": "Why it applies to this directory, in words.",
          "type": "string"
        }
      },
      "required": [
        "id",
        "path",
        "depth",
        "order",
        "composition",
        "reason",
        "local"
      ],
      "type": "object"
    }
  },
  "description": "The layer's directories, what each owes, and the contracts that apply.",
  "properties": {
    "directories": {
      "description": "Every directory asked for, sorted by path.",
      "items": {
        "$ref": "#/$defs/DirectoryNode"
      },
      "type": "array"
    },
    "root": {
      "description": "The layer root the tree is rooted at.",
      "type": "string"
    },
    "tallies": {
      "$ref": "#/$defs/DirectoryTallies",
      "description": "The directories in each state."
    }
  },
  "required": [
    "root",
    "tallies",
    "directories"
  ],
  "title": "DirectoryReport",
  "type": "object"
}

Policies

benchmark: required — a target on every transport the exposure declares; the cases are the input type's
cache: process — up to 8 entries in the process, 5s each, 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.

transport	state	cases	targets
direct	covered	4	whole-tree cold+warm one-directory cold+warm effective-everywhere cold+warm owed cold+warm
mcp	covered	4	whole-tree cold+warm one-directory cold+warm effective-everywhere cold+warm owed cold+warm
http	covered	4	whole-tree cold+warm one-directory cold+warm effective-everywhere cold+warm owed cold+warm