repository.info

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

{
  "$defs": {
    "AnswerObservation": {
      "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```",
      "properties": {
        "observed_at": {
          "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).",
          "type": "string"
        },
        "source": {
          "description": "What was read at that time: `index build` or `git read`.",
          "type": "string"
        },
        "stale_after": {
          "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.",
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "observed_at",
        "source"
      ],
      "type": "object"
    },
    "Diagnostic": {
      "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.",
      "properties": {
        "code": {
          "description": "A stable machine-readable code, e.g. `unknown_key`, `duplicate_identity`.",
          "type": "string"
        },
        "message": {
          "description": "What is wrong, for a person; the code is for a program.",
          "type": "string"
        },
        "path": {
          "description": "Repository-relative path of the file concerned, when there is one.",
          "type": [
            "string",
            "null"
          ]
        },
        "severity": {
          "$ref": "#/$defs/Severity",
          "description": "How bad."
        }
      },
      "required": [
        "severity",
        "code",
        "message"
      ],
      "type": "object"
    },
    "GitInfo": {
      "description": "What `git` said about the repository.",
      "properties": {
        "branch": {
          "description": "Branch name, or `None` when detached or unborn.",
          "type": [
            "string",
            "null"
          ]
        },
        "head": {
          "description": "Full commit id of HEAD, or `None` in an unborn repository.",
          "type": [
            "string",
            "null"
          ]
        },
        "toplevel": {
          "description": "Absolute path of the work tree top level.",
          "type": "string"
        },
        "working_tree": {
          "description": "`clean` or `dirty`, from `git status --porcelain`.",
          "type": "string"
        }
      },
      "required": [
        "toplevel",
        "working_tree"
      ],
      "type": "object"
    },
    "GitState": {
      "description": "What git says about the repository, or why it could not be asked.",
      "oneOf": [
        {
          "$ref": "#/$defs/GitInfo",
          "description": "`git` answered; the facts follow.",
          "properties": {
            "state": {
              "const": "available",
              "type": "string"
            }
          },
          "required": [
            "state"
          ],
          "type": "object"
        },
        {
          "description": "`git` could not be asked, or the root is not a work tree; the reason says which.",
          "properties": {
            "reason": {
              "description": "What `git` said, or why it could not be run.",
              "type": "string"
            },
            "state": {
              "const": "unavailable",
              "type": "string"
            }
          },
          "required": [
            "state",
            "reason"
          ],
          "type": "object"
        }
      ]
    },
    "Origin": {
      "description": "Where the declaration was read from.",
      "oneOf": [
        {
          "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.",
          "type": "string"
        }
      ]
    },
    "RepositoryInfo": {
      "description": "What the index knows about the repository it was built from.",
      "properties": {
        "discovery": {
          "description": "`vcs` or `filesystem`.",
          "type": "string"
        },
        "git": {
          "$ref": "#/$defs/GitState",
          "description": "What `git` said, or why it could not be asked."
        },
        "kind_sources": {
          "description": "The kinds files the reader was configured from: the distribution's, then the\nrepository's own when it has one.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "layer_schema": {
          "description": "The manifest's `schema`, `ai-repository/v1`.",
          "type": "string"
        },
        "observed": {
          "$ref": "#/$defs/RepositoryObservations",
          "default": {
            "git": {
              "observed_at": "",
              "source": ""
            },
            "index": {
              "observed_at": "",
              "source": ""
            }
          },
          "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."
        },
        "root": {
          "description": "The repository root, absolute.",
          "type": "string"
        },
        "scope_origin": {
          "$ref": "#/$defs/Origin",
          "description": "Where the scope was read from: `repository` or `distribution`."
        },
        "scope_path": {
          "description": "The scope file: repository-relative for the repository's own, the share path for\nthe distribution's default.",
          "type": "string"
        },
        "sections": {
          "additionalProperties": {
            "type": "string"
          },
          "description": "Manifest section name to repository-relative path.",
          "type": "object"
        },
        "source_classes": {
          "description": "Source class id to kind, in declared order.",
          "items": {
            "maxItems": 2,
            "minItems": 2,
            "prefixItems": [
              {
                "type": "string"
              },
              {
                "type": "string"
              }
            ],
            "type": "array"
          },
          "type": "array"
        }
      },
      "required": [
        "root",
        "layer_schema",
        "sections",
        "git",
        "discovery",
        "source_classes",
        "kind_sources",
        "scope_origin",
        "scope_path"
      ],
      "type": "object"
    },
    "RepositoryObservations": {
      "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```",
      "properties": {
        "git": {
          "$ref": "#/$defs/AnswerObservation",
          "description": "When git was asked: the branch, the head, the working tree."
        },
        "index": {
          "$ref": "#/$defs/AnswerObservation",
          "description": "When the index was built: the objects, the kinds, the diagnostics."
        }
      },
      "required": [
        "index",
        "git"
      ],
      "type": "object"
    },
    "Severity": {
      "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.",
      "oneOf": [
        {
          "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.",
          "type": "string"
        }
      ]
    },
    "State": {
      "description": "Whether every discovered file became an object.",
      "oneOf": [
        {
          "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.",
          "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"
    }
  },
  "description": "The repository, its layer, its git state, and the state of this process's index.",
  "properties": {
    "capabilities": {
      "$ref": "#/$defs/Summary",
      "description": "The capability registry, counted."
    },
    "diagnostics": {
      "description": "Every diagnostic the index produced.",
      "items": {
        "$ref": "#/$defs/Diagnostic"
      },
      "type": "array"
    },
    "kinds": {
      "additionalProperties": {
        "format": "uint",
        "minimum": 0,
        "type": "integer"
      },
      "description": "Objects per kind.",
      "type": "object"
    },
    "objects": {
      "description": "How many objects the index holds.",
      "format": "uint",
      "minimum": 0,
      "type": "integer"
    },
    "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."
    }
  },
  "required": [
    "repository",
    "state",
    "objects",
    "kinds",
    "diagnostics",
    "capabilities"
  ],
  "title": "RepositoryReport",
  "type": "object"
}