artifacts.list

The manifest `majordomus generate` commits as docs/generated/artifacts.json, reconciled with the working tree: every document with the encodings it is written in, and every file with its format, schema, source, size, hash and whether the file on disk still matches. Optionally narrowed to one document or one encoding. Reads only; `majordomus generate` writes and `majordomus generate --check` is the byte-for-byte verdict.

query
behaviorally_verified
module artifacts
#artifacts
#generation
#introspection

Exposure

Where this one definition is reachable. Absence is explicit: a surface not listed does not carry it.

surface	as
MCP	tool majordomus_artifacts resource majordomus://artifacts
HTTP	GET /api/v1/artifacts operationId artifacts.list
command line	—

Schemas

The canonical input and output, from the Rust types; the MCP tool schema and the OpenAPI parameters and responses are derived from these.

input · ArtifactsInput

The input of `artifacts.list`: the whole manifest, or one slice of it.

property	type	required	description
document	string \| null	no	Only the artifacts of this document (`registry`, `cli`, `openapi`, ...).
format	one of 2	no	Only the artifacts written in this encoding.

JSON Schema

{
  "$defs": {
    "ArtifactFormat": {
      "description": "The encoding one generated artifact is written in.",
      "oneOf": [
        {
          "const": "json",
          "description": "A JSON document: pretty-printed, one trailing newline, provenance as members.",
          "type": "string"
        },
        {
          "const": "yaml",
          "description": "The same document in the layer's YAML, provenance as a comment banner.",
          "type": "string"
        },
        {
          "const": "markdown",
          "description": "Markdown for a reader, provenance as an HTML comment.",
          "type": "string"
        },
        {
          "const": "text",
          "description": "Line-oriented text another program reads: the shell tool's allow-lists,\nprovenance as `#` comments.",
          "type": "string"
        }
      ]
    }
  },
  "additionalProperties": false,
  "description": "The input of `artifacts.list`: the whole manifest, or one slice of it.",
  "properties": {
    "document": {
      "description": "Only the artifacts of this document (`registry`, `cli`, `openapi`, ...).",
      "type": [
        "string",
        "null"
      ]
    },
    "format": {
      "anyOf": [
        {
          "$ref": "#/$defs/ArtifactFormat"
        },
        {
          "type": "null"
        }
      ],
      "description": "Only the artifacts written in this encoding."
    }
  },
  "title": "ArtifactsInput",
  "type": "object"
}

output · ArtifactReport

The answer of `artifacts.list`.

property	type	required	description
artifacts	array	yes	The files, in the manifest's order, after any filter.
documents	array	yes	The documents, in the manifest's order.
manifest	string	yes	The manifest this was read from, repository-relative.
present	boolean	yes	Whether the manifest is committed in this repository at all. A repository that has never run `majordomus generate` has no generated tree, which is a fact about it and not a failure of this call: every list below is then empty and every tally zero.
regenerate	string	yes	The command that rewrites every one of them.
schema	string	yes	The schema the manifest carries, empty when there is none to read.
tallies	reference	yes	The counts.
verify	string	yes	The command that decides staleness byte for byte, which is stronger than the hash.

JSON Schema

{
  "$defs": {
    "ArtifactFormat": {
      "description": "The encoding one generated artifact is written in.",
      "oneOf": [
        {
          "const": "json",
          "description": "A JSON document: pretty-printed, one trailing newline, provenance as members.",
          "type": "string"
        },
        {
          "const": "yaml",
          "description": "The same document in the layer's YAML, provenance as a comment banner.",
          "type": "string"
        },
        {
          "const": "markdown",
          "description": "Markdown for a reader, provenance as an HTML comment.",
          "type": "string"
        },
        {
          "const": "text",
          "description": "Line-oriented text another program reads: the shell tool's allow-lists,\nprovenance as `#` comments.",
          "type": "string"
        }
      ]
    },
    "ArtifactState": {
      "description": "Where one generated file stands against the tree it is committed in.",
      "oneOf": [
        {
          "const": "current",
          "description": "The file is there and its bytes hash to what the manifest recorded.",
          "type": "string"
        },
        {
          "const": "stale",
          "description": "The file is there and its bytes differ: it was edited, or the generator moved on.",
          "type": "string"
        },
        {
          "const": "missing",
          "description": "The manifest names it and the tree does not have it.",
          "type": "string"
        },
        {
          "const": "present",
          "description": "The file is there and the manifest records no hash for it: the manifest's own\nencodings, which cannot hash themselves. `generate --check` compares them.",
          "type": "string"
        }
      ]
    },
    "ArtifactTallies": {
      "description": "How many of each, so a caller needs no arithmetic of its own.",
      "properties": {
        "artifacts": {
          "description": "Files in the manifest, after any filter.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "current": {
          "description": "Hashes that match.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "documents": {
          "description": "Documents in the manifest.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "missing": {
          "description": "Files the manifest names and the tree lacks.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "present": {
          "description": "Files the manifest records no hash for.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "stale": {
          "description": "Hashes that do not.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        }
      },
      "required": [
        "documents",
        "artifacts",
        "current",
        "stale",
        "missing",
        "present"
      ],
      "type": "object"
    },
    "ArtifactView": {
      "description": "One generated file, as the manifest declares it and as the tree has it.",
      "properties": {
        "bytes": {
          "description": "The size the manifest recorded.",
          "format": "uint64",
          "minimum": 0,
          "type": [
            "integer",
            "null"
          ]
        },
        "document": {
          "description": "The document it projects.",
          "type": "string"
        },
        "format": {
          "$ref": "#/$defs/ArtifactFormat",
          "description": "The encoding."
        },
        "path": {
          "description": "Repository-relative path.",
          "type": "string"
        },
        "schema": {
          "description": "The JSON Schema its content satisfies, when it declares one.",
          "type": [
            "string",
            "null"
          ]
        },
        "sha256": {
          "description": "The hash the manifest recorded.",
          "type": [
            "string",
            "null"
          ]
        },
        "source": {
          "description": "One line: what it was derived from.",
          "type": "string"
        },
        "state": {
          "$ref": "#/$defs/ArtifactState",
          "description": "Where the file stands against it."
        }
      },
      "required": [
        "path",
        "document",
        "format",
        "source",
        "state"
      ],
      "type": "object"
    },
    "DocumentView": {
      "description": "One document, and the encodings it is committed in.",
      "properties": {
        "formats": {
          "description": "The encodings, in the manifest's order.",
          "items": {
            "$ref": "#/$defs/ArtifactFormat"
          },
          "type": "array"
        },
        "id": {
          "description": "The document id, shared by every encoding of it.",
          "type": "string"
        },
        "schema": {
          "description": "The schema id its structured encodings carry.",
          "type": [
            "string",
            "null"
          ]
        },
        "source": {
          "description": "One line: what it was derived from.",
          "type": "string"
        }
      },
      "required": [
        "id",
        "source",
        "formats"
      ],
      "type": "object"
    }
  },
  "description": "The answer of `artifacts.list`.",
  "properties": {
    "artifacts": {
      "description": "The files, in the manifest's order, after any filter.",
      "items": {
        "$ref": "#/$defs/ArtifactView"
      },
      "type": "array"
    },
    "documents": {
      "description": "The documents, in the manifest's order.",
      "items": {
        "$ref": "#/$defs/DocumentView"
      },
      "type": "array"
    },
    "manifest": {
      "description": "The manifest this was read from, repository-relative.",
      "type": "string"
    },
    "present": {
      "description": "Whether the manifest is committed in this repository at all. A repository that has\nnever run `majordomus generate` has no generated tree, which is a fact about it and\nnot a failure of this call: every list below is then empty and every tally zero.",
      "type": "boolean"
    },
    "regenerate": {
      "description": "The command that rewrites every one of them.",
      "type": "string"
    },
    "schema": {
      "description": "The schema the manifest carries, empty when there is none to read.",
      "type": "string"
    },
    "tallies": {
      "$ref": "#/$defs/ArtifactTallies",
      "description": "The counts."
    },
    "verify": {
      "description": "The command that decides staleness byte for byte, which is stronger than the hash.",
      "type": "string"
    }
  },
  "required": [
    "manifest",
    "present",
    "schema",
    "documents",
    "artifacts",
    "tallies",
    "regenerate",
    "verify"
  ],
  "title": "ArtifactReport",
  "type": "object"
}

Policies

benchmark: required — a target on every transport the exposure declares; the cases are the input type's
cache: process — up to 8 entries in the process, 5s each, scoped by the registry fingerprint

Benchmark targets

Derived from the registry for this repository: one requirement per transport, and the cases the input type provides. The whole matrix is on the benchmarks page.

transport	state	cases	targets
direct	covered	2	all cold+warm one-encoding cold+warm
mcp	covered	2	all cold+warm one-encoding cold+warm
http	covered	2	all cold+warm one-encoding cold+warm