repository.info

{
  "type": "object",
  "additionalProperties": false,
  "description": "No input.",
  "title": "Empty"
}

{
  "type": "object",
  "properties": {
    "repository": {
      "$ref": "#/$defs/RepositoryInfo",
      "description": "The repository: root, layer schema, sections, git state, discovery mode, source classes, kind sources."
    },
    "state": {
      "$ref": "#/$defs/State",
      "description": "`ok` when every discovered file became an object, `degraded` otherwise."
    },
    "objects": {
      "type": "integer",
      "format": "uint",
      "minimum": 0,
      "description": "How many objects the index holds."
    },
    "kinds": {
      "type": "object",
      "additionalProperties": {
        "type": "integer",
        "format": "uint",
        "minimum": 0
      },
      "description": "Objects per kind."
    },
    "diagnostics": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/Diagnostic"
      },
      "description": "Every diagnostic the index produced."
    },
    "capabilities": {
      "$ref": "#/$defs/Summary",
      "description": "The capability registry, counted."
    }
  },
  "required": [
    "repository",
    "state",
    "objects",
    "kinds",
    "diagnostics",
    "capabilities"
  ],
  "description": "The repository, its layer, its git state, and the state of this process's index.",
  "title": "RepositoryReport",
  "$defs": {
    "RepositoryInfo": {
      "type": "object",
      "properties": {
        "root": {
          "type": "string",
          "description": "The repository root, absolute."
        },
        "layer_schema": {
          "type": "string",
          "description": "The manifest's `schema`, `ai-repository/v1`."
        },
        "sections": {
          "type": "object",
          "additionalProperties": {
            "type": "string"
          },
          "description": "Manifest section name to repository-relative path."
        },
        "git": {
          "$ref": "#/$defs/GitState",
          "description": "What `git` said, or why it could not be asked."
        },
        "discovery": {
          "type": "string",
          "description": "`vcs` or `filesystem`."
        },
        "source_classes": {
          "type": "array",
          "items": {
            "type": "array",
            "prefixItems": [
              {
                "type": "string"
              },
              {
                "type": "string"
              }
            ],
            "minItems": 2,
            "maxItems": 2
          },
          "description": "Source class id to kind, in declared order."
        },
        "kind_sources": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "The kinds files the reader was configured from: the distribution's, then the\nrepository's own when it has one."
        },
        "scope_origin": {
          "$ref": "#/$defs/Origin",
          "description": "Where the scope was read from: `repository` or `distribution`."
        },
        "scope_path": {
          "type": "string",
          "description": "The scope file: repository-relative for the repository's own, the share path for\nthe distribution's default."
        },
        "observed": {
          "$ref": "#/$defs/RepositoryObservations",
          "description": "When the index and the git state it carries were read. Defaults to empty so that a\nrecord written before the freshness contract still reads.",
          "default": {
            "index": {
              "observed_at": "",
              "source": ""
            },
            "git": {
              "observed_at": "",
              "source": ""
            }
          }
        }
      },
      "required": [
        "root",
        "layer_schema",
        "sections",
        "git",
        "discovery",
        "source_classes",
        "kind_sources",
        "scope_origin",
        "scope_path"
      ],
      "description": "What the index knows about the repository it was built from."
    },
    "GitState": {
      "oneOf": [
        {
          "$ref": "#/$defs/GitInfo",
          "type": "object",
          "properties": {
            "state": {
              "type": "string",
              "const": "available"
            }
          },
          "required": [
            "state"
          ],
          "description": "`git` answered; the facts follow."
        },
        {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "What `git` said, or why it could not be run."
            },
            "state": {
              "type": "string",
              "const": "unavailable"
            }
          },
          "required": [
            "state",
            "reason"
          ],
          "description": "`git` could not be asked, or the root is not a work tree; the reason says which."
        }
      ],
      "description": "What git says about the repository, or why it could not be asked."
    },
    "GitInfo": {
      "type": "object",
      "properties": {
        "toplevel": {
          "type": "string",
          "description": "Absolute path of the work tree top level."
        },
        "head": {
          "type": [
            "string",
            "null"
          ],
          "description": "Full commit id of HEAD, or `None` in an unborn repository."
        },
        "branch": {
          "type": [
            "string",
            "null"
          ],
          "description": "Branch name, or `None` when detached or unborn."
        },
        "working_tree": {
          "type": "string",
          "description": "`clean` or `dirty`, from `git status --porcelain`."
        }
      },
      "required": [
        "toplevel",
        "working_tree"
      ],
      "description": "What `git` said about the repository."
    },
    "Origin": {
      "oneOf": [
        {
          "type": "string",
          "const": "repository",
          "description": "The repository's own, named by the manifest's `scope` section."
        },
        {
          "type": "string",
          "const": "distribution",
          "description": "The distribution's default, because the repository declares none."
        }
      ],
      "description": "Where the declaration was read from."
    },
    "RepositoryObservations": {
      "type": "object",
      "properties": {
        "index": {
          "$ref": "#/$defs/AnswerObservation",
          "description": "When the index was built: the objects, the kinds, the diagnostics."
        },
        "git": {
          "$ref": "#/$defs/AnswerObservation",
          "description": "When git was asked: the branch, the head, the working tree."
        }
      },
      "required": [
        "index",
        "git"
      ],
      "description": "The two pictures a process takes of the repository, each with when it was taken.\n\nA picture without a window is never stale, and its window is not serialized.\n\n```\nuse std::time::{Duration, UNIX_EPOCH};\nuse majordomus_cli::index::{AnswerObservation, RepositoryObservations};\nlet now = RepositoryObservations {\n    index: AnswerObservation::taken(\"index build\", UNIX_EPOCH, None),\n    git: AnswerObservation::taken(\"git read\", UNIX_EPOCH, Some(Duration::from_secs(120))),\n};\nlet json = serde_json::to_value(&now).unwrap();\nassert_eq!(json[\"git\"][\"stale_after\"], \"1970-01-01T00:02:00Z\");\nassert!(json[\"index\"].get(\"stale_after\").is_none());\nlet back: RepositoryObservations = serde_json::from_value(json).unwrap();\nassert_eq!(back, now);\n```"
    },
    "AnswerObservation": {
      "type": "object",
      "properties": {
        "observed_at": {
          "type": "string",
          "description": "RFC 3339 UTC, whole seconds: when the state behind the answer was read. Empty only\nin an answer from an index that was never built (a hand-made one in a test)."
        },
        "source": {
          "type": "string",
          "description": "What was read at that time: `index build` or `git read`."
        },
        "stale_after": {
          "type": [
            "string",
            "null"
          ],
          "description": "RFC 3339 UTC: after this the answer is not to be trusted as current even though\nnothing announced a change. Absent when there is no known blind spot."
        }
      },
      "required": [
        "observed_at",
        "source"
      ],
      "description": "When the state behind an answer was read: the freshness contract of a capability answer.\n\nDeclared once and carried in the output type of every answer that is a picture of\nstate, so that the output schema, OpenAPI, the MCP tool schemas and the command line's\nJSON all carry it without a transport of their own. It is set where the state is read —\nthe index build, the git read — never by the executor, which knows when a handler ran\nand not when the state it read was taken.\n\n```\nuse std::time::{Duration, UNIX_EPOCH};\nuse majordomus_cli::index::AnswerObservation;\nlet at = UNIX_EPOCH + Duration::from_secs(1_788_000_000);\nlet o = AnswerObservation::taken(\"git read\", at, Some(Duration::from_secs(120)));\nassert_eq!(o.observed_at, \"2026-08-29T10:40:00Z\");\nassert_eq!(o.stale_after.as_deref(), Some(\"2026-08-29T10:42:00Z\"));\nassert!(!o.is_stale_at(at + Duration::from_secs(120)));\nassert!(o.is_stale_at(at + Duration::from_secs(121)));\n```"
    },
    "State": {
      "oneOf": [
        {
          "type": "string",
          "const": "ok",
          "description": "Every discovered file became an object."
        },
        {
          "type": "string",
          "const": "degraded",
          "description": "At least one file could not be read; the diagnostics say which."
        }
      ],
      "description": "Whether every discovered file became an object."
    },
    "Diagnostic": {
      "type": "object",
      "properties": {
        "severity": {
          "$ref": "#/$defs/Severity",
          "description": "How bad."
        },
        "code": {
          "type": "string",
          "description": "A stable machine-readable code, e.g. `unknown_key`, `duplicate_identity`."
        },
        "path": {
          "type": [
            "string",
            "null"
          ],
          "description": "Repository-relative path of the file concerned, when there is one."
        },
        "message": {
          "type": "string",
          "description": "What is wrong, for a person; the code is for a program."
        }
      },
      "required": [
        "severity",
        "code",
        "message"
      ],
      "description": "One finding about the declarative state, named by a stable code, tied to a path where\nthere is one, and carrying the command that reproduces it where there is one."
    },
    "Severity": {
      "oneOf": [
        {
          "type": "string",
          "const": "info",
          "description": "Worth knowing; changes nothing."
        },
        {
          "type": "string",
          "const": "warning",
          "description": "Something to look at; the object is still served."
        },
        {
          "type": "string",
          "const": "error",
          "description": "The file is excluded and the index is degraded."
        }
      ],
      "description": "How bad a diagnostic is. `Error` excludes the file it concerns from the index and puts\nthe index into the degraded state; `Warning` and `Info` do neither."
    },
    "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."
    }
  }
}