environment.explain

{
  "additionalProperties": false,
  "description": "Which field's provenance to explain.",
  "properties": {
    "field": {
      "description": "The field in dotted form (`services.url`, `capabilities.objects`); every field when\nabsent.",
      "type": [
        "string",
        "null"
      ]
    }
  },
  "title": "ExplainInput",
  "type": "object"
}

{
  "$defs": {
    "Confidence": {
      "description": "How far a resolved value can be trusted.",
      "oneOf": [
        {
          "const": "exact",
          "description": "Read from its canonical source during this resolution.",
          "type": "string"
        },
        {
          "const": "cached",
          "description": "Read from a cache whose fingerprint still matches its inputs.",
          "type": "string"
        },
        {
          "const": "unknown",
          "description": "Not resolved.",
          "type": "string"
        }
      ]
    },
    "FieldSource": {
      "description": "Where one field of the snapshot came from. This is what makes an inferred system\ndebuggable: every fact can name the thing that decided it, so \"why does it say that\"\nis answered by the tool rather than by reading its source.",
      "properties": {
        "confidence": {
          "$ref": "#/$defs/Confidence",
          "description": "How certain the value is."
        },
        "field": {
          "description": "The field, in dotted form: `services.cockpit.url`, `vcs.branch`.",
          "type": "string"
        },
        "resolver": {
          "description": "The part of this executable that read it.",
          "type": "string"
        },
        "source": {
          "description": "What decided it: a file, a command, a compile-time constant, the cache.",
          "type": "string"
        },
        "value": {
          "description": "The value as it appears in the snapshot, rendered for a person; absent for a field\nthat resolved to nothing.",
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "field",
        "source",
        "resolver",
        "confidence"
      ],
      "type": "object"
    },
    "Resolution": {
      "description": "How completely a snapshot was resolved. Carried in the snapshot because a consumer must\nbe able to tell \"there is no server running\" from \"nobody looked\".",
      "oneOf": [
        {
          "const": "fast",
          "description": "Only what is cheap enough for a shell prompt; the rest from the cache.",
          "type": "string"
        },
        {
          "const": "full",
          "description": "Everything, including the index. Writes the cache.",
          "type": "string"
        }
      ]
    }
  },
  "description": "Where the values of one snapshot came from.",
  "properties": {
    "fields": {
      "description": "One entry per field, in the order the resolver produced them.",
      "items": {
        "$ref": "#/$defs/FieldSource"
      },
      "type": "array"
    },
    "resolution": {
      "$ref": "#/$defs/Resolution",
      "description": "How the snapshot behind these entries was resolved."
    }
  },
  "required": [
    "resolution",
    "fields"
  ],
  "title": "EnvironmentProvenance",
  "type": "object"
}