HTTP API: directories

The layer's directories as a hierarchy: the contract each one declares, what it owes and which contract said so, and the chain that applies to it once inheritance is resolved.

Rendered from docs/generated/openapi.json, which the executable generates from its capability registry and CI refuses stale. The raw document is at /openapi.json; a running server serves the same document at its own /openapi.json and Swagger UI at /swagger.

directories

The layer's directories as a hierarchy: the contract each one declares, what it owes and which contract said so, and the chain that applies to it once inheritance is resolved.

GET /api/v1/directories directories.list

The layer's directory contracts

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
benchmark required
cache process (max_entries=8, ttl_seconds=5)
MCP tool majordomus_directories
MCP resource {"name": "directories", "uri": "majordomus://directories"}

Query parameters

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

Try it

The port is whatever the server logged; 8741 is the one it asks for first. The values are the operation's first example.

curl -s "http://127.0.0.1:8741/api/v1/directories?path=.ai%2Frepo%2Frules&effective=true&state=owed"

Tested by apps/majordomus-cli/tests/http_serve.rs, which replays the route with these values against a server on a real socket.

Responses

status	body	meaning
200	DirectoryReport	The layer's directory contracts: the result.
400	ErrorBody	`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.
404	ErrorBody	`not_found`: The input names something the repository does not hold.
500	ErrorBody	`internal`: The capability failed for a reason of its own; the message names it.
default	ErrorBody	Any other failure the transport reports: 405 `method_not_allowed` for another method on this path, 400 `invalid_input` for a body that is not a JSON object.

Schemas

The components only this tag's operations use. Each row is the type's own field, its doc comment the description; a type another page owns links there.

ContractView

object

A directory contract as the document declares it, before anything is inherited.

property	type	required	description
id	string	yes	The document's identity; it survives a move, the file name does not.
path	string	yes	The document's path, repository-relative.
title	string \| null	no	One line naming the directory.
description	string \| null	no	One line saying what the directory is for.
status	string	yes	`active` or `deprecated`; a deprecated document is listed and never applied.
scope	string	yes	`directory`, `subtree` or `explicit`: how far the document reaches.
composition	string	yes	`extend`, `replace` or `final`: how it composes with what is above it.
order	integer (int64)	yes	Ties within one depth are broken by this, then by path.
providers	array of string	yes	`*`, or the providers the document is written for.
audience	array of string	yes	Who it addresses; both when it says nothing.
tracks	array of string	no	Pathspecs whose change names this document for review.
children_require_contract	boolean \| null	no	Whether the directories below owe a contract, when this document says.
children_exempt	array of string	no	Subtrees below this one that owe nothing: carried, not authored here.

Used by DirectoryNode

DirectoryNode

object

One directory of the layer, what it owes, and what applies to it.

property	type	required	description
path	string	yes	Repository-relative, forward slashes.
depth	integer (uint)	yes	Segments below the layer root; the root itself is 0.
parent	string \| null	no	The directory above, when it is inside the layer.
children	array of string	no	The directories immediately below, sorted.
state	DirectoryState → DirectoryState	yes	Whether it carries the contract it owes.
requires_contract	boolean	yes	Whether a contract is owed here at all.
governed_by	string \| null	no	The contract that made the requirement explicit, when one did.
exempted_by	string \| null	no	The contract that released this subtree, when one did.
objects	integer (uint)	yes	How many objects of any kind the index holds directly in this directory.
contract	ContractView \| null → ContractView	no	The contract this directory declares, before inheritance.
effective	array of EffectiveEntry → EffectiveEntry	no	The contracts that apply here once inheritance is resolved, least specific first. Present when the request asked for it, or when it asked about one path.

Used by DirectoryReport

DirectoryReport

object

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

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

Used by directories.list

DirectoryState

"documented" | "exempt" | "owed"

Whether a directory of the layer carries the contract it owes.

documentedIt carries a context document of its own.
exemptIt owes none, because a contract above it says so.
owedIt owes one and has none.

Used by directories.list DirectoryNode

DirectoryTallies

object

How many directories are in each state.

property	type	required	description
directories	integer (uint)	yes	Every directory of the layer the index knows.
documented	integer (uint)	yes	Carrying a contract of their own.
exempt	integer (uint)	yes	Released by a contract above them.
owed	integer (uint)	yes	Owing a contract and carrying none.

Used by DirectoryReport

EffectiveEntry

object

One contract in a directory's effective chain, in the order it is applied.

property	type	required	description
id	string	yes	The document's identity.
path	string	yes	The document's path.
depth	integer (uint)	yes	Depth below the layer root; less is less specific and applies first.
order	integer (int64)	yes	The declared order, the second sort key.
composition	string	yes	`extend`, `replace` or `final`.
reason	string	yes	Why it applies to this directory, in words.
local	boolean	yes	True for the directory's own document, false for one it inherits.

Used by DirectoryNode