served.show

{
  "additionalProperties": false,
  "description": "The input of `served.show`: the commit every record is re-judged against, and\noptionally a single deployment. `HEAD` and every deployment when absent.\n\n```\nuse majordomus_cli::capability::builtin::served::ShowInput;\nlet input: ShowInput = serde_json::from_str(r#\"{\"deployment\":\"pages\"}\"#).unwrap();\nassert_eq!(input.deployment.as_deref(), Some(\"pages\"));\nassert!(input.commit.is_none(), \"absent means HEAD\");\n// a field this operation does not have is refused rather than ignored\nassert!(serde_json::from_str::<ShowInput>(r#\"{\"url\":\"https://x\"}\"#).is_err());\n```",
  "properties": {
    "commit": {
      "description": "The commit each record is re-judged against, any revision git resolves; `HEAD` when\nabsent.",
      "type": [
        "string",
        "null"
      ]
    },
    "deployment": {
      "description": "Only this deployment.",
      "type": [
        "string",
        "null"
      ]
    }
  },
  "title": "ShowInput",
  "type": "object"
}

{
  "$defs": {
    "BuildIdentity": {
      "description": "The build identity a deployment serves, as far as this module relies on it. Other\nfields of the served document are ignored rather than refused: the document is written\nby another program, and a field it adds is not a malformation.\n\n```\nuse majordomus_cli::served::BuildIdentity;\nlet id = BuildIdentity {\n    commit: \"a\".repeat(40),\n    dirty: false,\n    source_version: Some(\"0.7.0\".into()),\n    source_hash: None,\n};\n// what is judged is the commit and whether the tree it was built from was committed\nassert_eq!(id.commit.len(), 40);\nassert!(!id.dirty);\n```",
      "properties": {
        "commit": {
          "description": "The full commit the served build was made from.",
          "type": "string"
        },
        "dirty": {
          "description": "Whether the tree it was built from had uncommitted changes. A dirty build names a\ncommit it does not equal, so it proves no commit.",
          "type": "boolean"
        },
        "source_hash": {
          "description": "The fingerprint of the site's canonical inputs, when the build states one.",
          "type": [
            "string",
            "null"
          ]
        },
        "source_version": {
          "description": "The version the build states, when it states one.",
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "commit",
        "dirty"
      ],
      "type": "object"
    },
    "DeploymentStanding": {
      "description": "One deployment's newest record and what it proves about the commit asked. Both are\ncarried: the recorded judgement is what was seen, `now` is what it still proves.\n\n```\nuse majordomus_cli::capability::builtin::served::DeploymentStanding;\nuse majordomus_cli::served::ServedVerdict;\nlet json = r#\"{\"deployment\":\"pages\",\"observation\":{\"schema\":\"majordomus.served-observation/v1\",\n  \"deployment\":\"pages\",\"url\":\"https://majordomus.dev/build.json\",\n  \"expected\":\"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"verdict\":\"served\",\n  \"reason\":\"the deployment serves aaaaaaaaaaaa\",\"at\":\"1970-01-01T00:00:00Z\"},\n  \"now\":{\"verdict\":\"stale\",\"reason\":\"it does not contain bbbbbbbbbbbb\"}}\"#;\nlet s: DeploymentStanding = serde_json::from_str(json).unwrap();\n// seen as served, and no longer proving the commit asked about\nassert_eq!(s.observation.judgement.verdict, ServedVerdict::Served);\nassert_eq!(s.now.verdict, ServedVerdict::Stale);\n```",
      "properties": {
        "deployment": {
          "description": "The deployment name.",
          "type": "string"
        },
        "now": {
          "$ref": "#/$defs/Judgement",
          "description": "That record re-judged against the commit asked about. This, not the recorded\njudgement, is what a reader acts on."
        },
        "observation": {
          "$ref": "#/$defs/Observation",
          "description": "The newest record of it."
        }
      },
      "required": [
        "deployment",
        "observation",
        "now"
      ],
      "type": "object"
    },
    "Judgement": {
      "description": "The judgement of one served identity against one expected commit, with its reason. The\nreason travels with the verdict so that every surface can say *why* without re-deriving\nit.\n\n```\nuse majordomus_cli::served::{judge, Fetched, Judgement, ServedVerdict};\nlet j: Judgement = judge(&Err(Fetched::Unreachable(\"timeout\".into())), &\"a\".repeat(40), &fake());\nassert_eq!(j.verdict, ServedVerdict::Unreachable);\nassert!(j.reason.contains(\"timeout\"));\n# use majordomus_cli::served::Ancestry;\n# struct N; impl Ancestry for N {\n#     fn has(&self, _: &str) -> Option<bool> { Some(true) }\n#     fn contains(&self, _: &str, _: &str) -> Option<bool> { Some(true) }\n# }\n# fn fake() -> impl Ancestry { N }\n```",
      "properties": {
        "reason": {
          "description": "Why, in one line a reader can act on.",
          "type": "string"
        },
        "verdict": {
          "$ref": "#/$defs/ServedVerdict",
          "description": "The verdict."
        }
      },
      "required": [
        "verdict",
        "reason"
      ],
      "type": "object"
    },
    "Observation": {
      "description": "One observation of one deployment, as recorded: what was asked, what was served, what\nwas judged and when. Everything needed to judge it again later is in the record, which\nis what lets `Observation::rejudge` answer without probing.\n\n```\nuse majordomus_cli::served::{observe, Fetch, Fetched, GitAncestry, Observation, OBSERVATION_SCHEMA};\nuse std::{path::Path, time::SystemTime};\nstruct None_;\nimpl Fetch for None_ {\n    fn fetch(&self, _: &str) -> Fetched { Fetched::Unreachable(\"no route\".into()) }\n}\nlet git = GitAncestry { root: Path::new(env!(\"CARGO_MANIFEST_DIR\")) };\nlet o: Observation = observe(\"pages\", \"https://s\", \"build.json\", &\"a\".repeat(40), &None_,\n                              &git, SystemTime::UNIX_EPOCH);\nassert_eq!(o.schema, OBSERVATION_SCHEMA);\nassert_eq!(o.url, \"https://s/build.json\");\nassert_eq!(o.at, \"1970-01-01T00:00:00Z\");\n```",
      "properties": {
        "at": {
          "description": "When, RFC 3339 UTC.",
          "type": "string"
        },
        "deployment": {
          "description": "Which deployment: the name the caller observed it under (`pages`, or a deployment\nobject's id).",
          "type": "string"
        },
        "expected": {
          "description": "The commit that was expected, full.",
          "type": "string"
        },
        "reason": {
          "description": "Why, in one line a reader can act on.",
          "type": "string"
        },
        "schema": {
          "description": "Always `OBSERVATION_SCHEMA`.",
          "type": "string"
        },
        "served": {
          "anyOf": [
            {
              "$ref": "#/$defs/BuildIdentity"
            },
            {
              "type": "null"
            }
          ],
          "description": "What was served, when a build identity was received."
        },
        "url": {
          "description": "The identity URL probed.",
          "type": "string"
        },
        "verdict": {
          "$ref": "#/$defs/ServedVerdict",
          "description": "The verdict."
        }
      },
      "required": [
        "schema",
        "deployment",
        "url",
        "expected",
        "verdict",
        "reason",
        "at"
      ],
      "type": "object"
    },
    "ServedVerdict": {
      "description": "What an observation says about the expected commit. Only `ServedVerdict::Served` is a\nproof; the other five are each a different reason the question was not answered yes.\n\n```\nuse majordomus_cli::served::ServedVerdict;\n// a measured no and an unanswered question are never spelled the same\nassert!(ServedVerdict::Served.passes());\nassert_eq!(ServedVerdict::Stale.exit_code(), 10);\nassert_eq!(ServedVerdict::Unreachable.exit_code(), 12);\n```",
      "oneOf": [
        {
          "const": "served",
          "description": "The served build is the expected commit or contains it. The only passing verdict.",
          "type": "string"
        },
        {
          "const": "stale",
          "description": "The served build does not contain the expected commit: the deployment is behind.",
          "type": "string"
        },
        {
          "const": "unreachable",
          "description": "Nothing was received. The deployment was not measured.",
          "type": "string"
        },
        {
          "const": "malformed",
          "description": "Something was received and it is not a build identity.",
          "type": "string"
        },
        {
          "const": "dirty",
          "description": "The served build was made from an uncommitted tree, so it proves no commit.",
          "type": "string"
        },
        {
          "const": "undecided",
          "description": "The served commit is not in this clone, or git could not be asked; containment is\nundecided. Fetching the remote usually turns this into an answer.",
          "type": "string"
        }
      ]
    }
  },
  "description": "Every deployment's standing against one commit: the answer `served.show` gives on the\ncommand line, over HTTP and to an MCP client, from one derivation.\n\n```\nuse majordomus_cli::capability::builtin::served::{standing, ServedStanding};\nuse majordomus_cli::served::{Ancestry, OBSERVATIONS_PATH};\n# struct A; impl Ancestry for A {\n#     fn has(&self, _: &str) -> Option<bool> { Some(true) }\n#     fn contains(&self, _: &str, _: &str) -> Option<bool> { Some(true) } }\nlet dir = tempfile::tempdir().unwrap();\nlet s: ServedStanding = standing(dir.path(), &\"a\".repeat(40), None, &A);\nassert_eq!(s.observations, OBSERVATIONS_PATH);\nassert!(s.deployments.is_empty(), \"nothing observed yet\");\nassert_eq!(s.unreadable, 0);\n```",
  "properties": {
    "deployments": {
      "description": "One entry per deployment observed, in name order.",
      "items": {
        "$ref": "#/$defs/DeploymentStanding"
      },
      "type": "array"
    },
    "expected": {
      "description": "The full commit every record was re-judged against.",
      "type": "string"
    },
    "observations": {
      "description": "The checkout-local file the records were read from.",
      "type": "string"
    },
    "unreadable": {
      "description": "Lines of that file that were not readable observations.",
      "format": "uint",
      "minimum": 0,
      "type": "integer"
    }
  },
  "required": [
    "expected",
    "observations",
    "unreadable",
    "deployments"
  ],
  "title": "ServedStanding",
  "type": "object"
}