health.report

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

{
  "type": "object",
  "properties": {
    "status": {
      "$ref": "#/$defs/HealthStatus",
      "description": "The worst check's status."
    },
    "repository": {
      "$ref": "#/$defs/HealthStatus",
      "description": "The worst status among the dimensions that describe the repository at this commit:\nevery check but the ones in `PROCESS_DIMENSIONS`. A process that is no server —\nthe command line, or the reader of a published snapshot (ADR 0141) — cannot decide\nwho is attached or what the mesh runtime did, and says `unknown` for them; this is\nthe verdict that is the same whichever process read the repository, and it is what a\npublication shows first."
    },
    "tallies": {
      "type": "object",
      "additionalProperties": {
        "type": "integer",
        "format": "uint",
        "minimum": 0
      },
      "description": "How many checks stand where, by status word."
    },
    "checks": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/HealthCheck"
      },
      "description": "Every dimension, in a stable order."
    },
    "observed": {
      "type": "object",
      "additionalProperties": {
        "$ref": "#/$defs/AnswerObservation"
      },
      "description": "When the state a check decided on was read, by check id: the freshness contract\n(`crate::index::AnswerObservation`). A check absent here decided live, during this call.\n`layer` and `git` are here because they judge the picture the index took, which is\nas old as the index."
    }
  },
  "required": [
    "status",
    "repository",
    "tallies",
    "checks"
  ],
  "description": "The health of what this process serves.",
  "title": "Health",
  "$defs": {
    "HealthStatus": {
      "oneOf": [
        {
          "type": "string",
          "const": "ok",
          "description": "The engine that decides this dimension is satisfied."
        },
        {
          "type": "string",
          "const": "warn",
          "description": "Nothing is broken and something is worth looking at."
        },
        {
          "type": "string",
          "const": "fail",
          "description": "The engine that decides this dimension is not satisfied."
        },
        {
          "type": "string",
          "const": "unknown",
          "description": "This process cannot decide it, and says so rather than reporting `ok`."
        }
      ],
      "description": "Where one dimension of the system stands. Ordered by severity, so the worst check\ndecides the whole."
    },
    "HealthCheck": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "A stable id, `[a-z][a-z0-9-]*`."
        },
        "title": {
          "type": "string",
          "description": "The short name."
        },
        "status": {
          "$ref": "#/$defs/HealthStatus",
          "description": "Where it stands."
        },
        "detail": {
          "type": "string",
          "description": "One line: what the engine decided and on what."
        },
        "decided_by": {
          "type": "string",
          "description": "The engine that decided it, named so the reader knows what to fix."
        },
        "evidence": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "What reproduces the verdict: a command, or a path."
        },
        "findings": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Findings behind the verdict, when the engine produced any: the diagnostic\nmessages, the stale files, the missing coverage lines."
        }
      },
      "required": [
        "id",
        "title",
        "status",
        "detail",
        "decided_by"
      ],
      "description": "One dimension of the system, decided by one engine, with what a reader needs to check\nit themselves."
    },
    "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```"
    }
  }
}